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
- stk_build, stk_count, stk_read_num, stk_where