Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/stk_read_num.html
AHELP for CIAO 4.16

stk_read_num

Context: Tools::Stacks

Synopsis

stk_read_num is used to read one element of a user-defined stack. The output is to the outelement field of the stk_read_num parameter file.

Syntax

stk_read_num infile num [outelement] [echo] [verbose]

Description

The stk_read_num program takes an infile string, and a number (num) as input. The infile string can be defined in any variation that is accepted by the ASCDS stack API. These variations include the use of @ and added directory paths (ie. @/tmp/foo).

num can be any number from 1 up to the number of items in the stack. If num is specified as less than 1, then stk_read_num will give a warning and continue with the value of 1. If num is defined as greater than the number of items in the stack, stk_read_num will give an error and exit.

The output parameter is called outelement. outelement will be populated with the value found at the num'th item of the stack built by the infile string.

The level of verbosity is defined by the verbose parameter. The user can optionally set verbose from 0 (for no output) up to 3 (for the most output.)


Examples

Example 1

stk_read_num infile="red blue green" num=2

stk_read_num will build a stack from the infile string "red blue green", look at the second element of the stack, and (in this case) set outelement to blue.

Example 2

stk_read_num infile="@threecolors white" num=4

stk_read_num will build a stack from the infile string "@threecolors white". If the file threecolors contains 3 entries, then stk_read_num will look at the fourth element of the stack, and set outelement to white.


Parameters

name type ftype def min max reqd stacks
infile file input       yes yes
num integer   1     yes  
outelement string         no  
echo boolean   no     no  
verbose integer   0 0 5 no  

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=yes)

The string used to build a stack.

The infile string can be defined in any variation that is accepted by the ASCDS stack API. These variations include the use of @ and added directory paths (ie. @/tmp/foo). Zero or more stacks may be used as input.

Parameter=num (integer required default=1)

The number of the element to be retieved from the stack.

num can be any number from 1 up to the number of items in the stack. If num is specified as less than 1, then stk_read_num will give a warning and continue with the value of 1. If num is defined as greater than the number of items in the stack, stk_read_num will give an error and exit.

Parameter=outelement (string not required)

The element retrieved from the stack.

This is the tool output. Outelement will hold the value found in the num'th item of the stack built by the infile string.

Parameter=echo (boolean not required default=no)

Echo value to screen?

Determines if the retrieved value is printed to the screen in addition to being stored in the parameter file.

Parameter=verbose (integer not required default=0 min=0 max=5)

Determines the level of output the user will see when the program is run.

Each level adds additional output. 0 - no output. 1 - shows non-hidden parameters. 2 - shows hidden parameters. 3 - gives the user information about which stage of the program is executing.


Bugs

There are no known bugs for this tool.

See Also

concept
stack
tools::stacks
stk_build, stk_count, stk_where