4.2 Image
Label Access API
This
Section describes the subroutines that make up the programmer's interface for
label processing.
4.2.1 x/zladd—Add
information to an existing label item
call xladd(unit, type, key, value, status, <optionals>, ' ')
status = zladd(unit, type, key, value, <optionals>, 0);
x/zladd
adds label items or values to multi-valued label items to a label. Strings in
the image label are delimited by single quotes (
').
A single quote in an input string will be repeated before being put in the
label. On output (from
x/zlget),
the pair will be returned as one single quote. In other words, the repeating of
quotes is transparent to the application program.
Arguments:
- UNIT:
input, integer
Unit
of associated file.
- TYPE:
input, string
´PROPERTY',
'HISTORY' or 'SYSTEM'.
- KEY:
input, string
The
key word of the label item.
- VALUE:
input, array (size: NELEMENT)
Holds
the values of the label item. The type of argument required depends on the
FORMAT optional given. For single values, INT requires an integer, REAL
requires floating point (single-precision), and STRING requires a simple string
argument ( (char *) in C, CHARACTER in FORTRAN). For multi-valued items (if
NELEMENT is not 1), INT and REAL take single-dimension arrays of integers or
reals. A STRING must be a two-dimensional array of characters in either FORTRAN
or C.
For
example, a string array capable of handling 10 elements, with 80 characters in
each element, is declared in C:
char
value[10][80];
The
standard C null string terminator is required, so the above array could only
hold 79 characters. You will still pass in the length (in ULEN) as 80. ULEN is
required for C strings that have more than one element. It is not legal to pass
in an array of string pointers; the value must be a true array of characters.
In
FORTRAN you use a CHARACTER array:
CHARACTER*80
VALUE (10)
ULEN
is not required, because the character descriptor contains the length of each
string. Trailing spaces are stripped from FORTRAN strings by the executive; you
can not add a label item that ends in a blank.
- STATUS:
output, integer
Error
status. The possible errors are listed in
10
Appendix B: Error Messages.
Optional
arguments:
- ERR_ACT:
input, string
Indicates
the action to be taken by the Executive when an error condition is raised as a
result of a call to this routine. A valid string may contain one or more of
three characters in any order, 'A', 'U', 'S'. The presence of each character
has the following meanings:
- A:
an error will cause an immediate program abort. Otherwise, the routine will
return an error number in STATUS.
- U:
an error will cause the string that the user has specified with the ERR_MESS
optional to be printed.
- S:
an error will cause a system message to be printed.
The
three values are independent of each other. Thus 'SA' will cause a system
message to be printed and the program to abort if an error occurs. If ERR_ACT
consists only of blanks, an error will cause routine to return an error number
in STATUS.
If
ERR_ACT is not specified, then the action defaults to the value of the LAB_ACT
optional to
x/zvopen
(the default for LAB_ACT is specified by
x/zveaction).
- ERR_MESS:
input, string
Holds
the user message that the programmer wishes printed when an error occurs as
directed by ERR_ACT. Default is specified by
x/zveaction.
if the ERR_ACT option is not specified, and the LAB_ACT option given to
x/zvopen
specifies a message be printed, the message given by LAB_MESS,
not
ERR_MESS is printed.
- FORMAT:
input, format
Indicates
the format of the given label item value. Valid values are: 'INT', 'REAL',
‘DOUB’ and 'STRING'. The VALUE array type should match FORMAT, i.e.
float for REAL, double for DOUB, etc. See
Table 6: C Declarations for Run-Time Library Arguments)
for matching C declarations. See
Table 6: FORTRAN declarations for pixel types
for matching FORTRAN declarations.
FORMAT
is required.
If
the value in the FORMAT optional does not match the format of the currently
existing label item, the label item is changed to match the optional. If this
is not possible (i.e., a non-numeric string being changed to an integer), an
error is returned.
- LEVEL:
input, integer
In
the ADD routine, which allows label items to be added to a label, a level may
be associated with a label item when that item is added. LEVEL holds the
positive integer which is the level of the label item. (NOT YET AVAILABLE)
- ELEMENT:
input, integer
For
a multi-value item, the starting point to add the VALUE. If there are 4
elements currently, and ELEMENT is 3, then the new value will become the third
element, and the old third and fourth will either be moved down to make room
(if MODE is 'INSERT'), or will be replaced (if MODE is ‘REPLACE'). A
value of -1 says to add the element at the end, after all existing elements.
The default is -1, i.e. to add it at the end.
- NELEMENT:
input, integer
The
number of values to be added to a multi-value item. Default: 1.
- HIST:
input, string
If
TYPE is 'HISTORY' then this argument holds the name of the processing task that
identifies the particular history subset in which 'KEY' may be found; if not
entered, defaults to current task.
- INSTANCE:
input, integer
If
TYPE is 'HISTORY’, ‘INSTANCE’ specifies into which instance
the name of the task from ‘HIST’ will be entered. If TYPE is
‘PROPERTY’, ‘INSTANCE’ specifies into which instance
the name of the property set from ‘PROPERTY’ will be entered.
Attempting to add a label to a non-esistent property instance will cause a new
instance to be created. Instance numbers created may not match instance number
entered. If there are 5 instances now, and you add instance 10, the label will
go in a new instance 6. INSTANCE=0 forces creation of a new instance. Default:
1.
- ULEN:
input, integer
The
length of an input string. This optional only applies if the FORMAT is STRING.
For multi-valued items, ULEN is the maximum length of each string in the array,
i.e. it is the size of the first dimension of the array. ULEN is required in
some cases, and it is ignored in others. These are explained below.
There
are two ways to pass strings: C char and FORTRAN CHARACTER. See the VALUE
argument for an example of each.
- C:
If
NELEMENT is not 1 (multi-valued), then ULEN is required
.
If
NELEMENT is 1, then ULEN is optional. If present, it is used, otherwise the
length is the null-terminated length of the string.
- FORTRAN
CHARACTER:
ULEN
is
always ignored.
The
length is obtained from the character descriptor.
- MODE:
input, string
Specifies
what to do with labels that already exist. There are three allowable values:
'ADD', 'INSERT', and 'REPLACE'.
- 'ADD':
this
is the default action. If the label already exists, a DUPLICATE_KEY error is
returned, and the label is not changed. If the label doesn't exist, it is
created.
- 'INSERT':
If the label does not exist in the file, a new one is created. If it does
exist, then all elements that are added are inserted into the existing list of
elements. All elements in the old label past the point of insertion are moved
down to make room. For example, if the label has 4 elements, and you are adding
2 elements (NELEMENT is 2) at position 3 (ELEMENT is 3), then the two new
elements would become numbers 3 and 4, and the old 3 and 4 would get moved to
numbers 5 and 6.
- 'REPLACE':
If the label does not exist in the file, a new one is created. If it does
exist, then all elements that are added replace any elements in the old label
with the same sequence numbers (if any). For example, if the label has 5
element s, and you are adding 2 elements (NELEMENT is 2) at position 3 (ELEMENT
is 3), then the two new elements would replace the old element numbers 3 and 4.
Items 1, 2, and 5 remain unchanged. 'REPLACE' is not a reliable way to replace
the entire contents of a label, as you do not always know ahead of time how
many elements are present. To do that, call
x/zldel
and
x/zladd
in sequence.
- PROPERTY,
string: The name of the property set that the label routine is accessing The
PROPERTY optional argument is only valid if the TYPE argument of the above
routines is set to “PROPERTY”. See
4.1.2.1
Using Property Labels,
for more information.
4.2.2 x/zldel—Remove
a label item
call xldel(unit, type, key, status, <optionals>, ' ')
status = zldel(unit, type, key, <optionals>, 0);
x/zldel
removes a label item from a file that the user owns (an output file on a
command line) or for which the user has update privilege.
x/zldel
permits the partial deletion of values in a multi-value label item.
Arguments:
- UNIT:
input, integer
Unit
of associated file.
- TYPE:
input, string
´PROPERTY',
'HISTORY' or 'SYSTEM'.
- KEY:
input, string
The
key word of the desired label item.
- STATUS:
output integer
Error
status. The possible errors are listed in
Appendix B: Error Messages
(page 140).
Optional
arguments:
- ERR_ACT:
input, string
Indicates
the action to be taken by the Executive when an error condition is raised as a
result of a call to this routine. A valid string may contain one or more of
three characters in any order, 'A', 'U', 'S'. The presence of each character
has the following meanings:
- A:
an error will cause an immediate program abort.
Otherwise,
the routine will return an error number in STATUS.
- U:
an error will cause the string that the user has specified with the ERR_MESS
optional to be printed.
- S:
an error will cause a system message to be printed.
The
three values are independent of each other. Thus 'SA' will cause a system
message to be printed and the program to abort if an error occurs. If ERR_ACT
consists only of blanks, an error will cause routine to return an error number
in STATUS.
If
ERR_ACT is not specified, then the action defaults to the value of the LAB_ACT
optional to
x/zvopen
(the default for LAB_ACT is specified by
x/zveaction).
- ERR_MESS:
input, string
Holds
the user message that the programmer wishes printed when an error occurs as
directed by ERR_ACT. Default is specified by
x/zveaction.
If
the ERR_ACT option is not specified, and the LAB_ACT option given to
x/zvopen
specifies a message be printed, the message given by LAB_MESS,
not
ERR_MESS is printed.
- ELEMENT:
input, integer
For
a multi-value item, the starting value to delete. Default: 1.
- NELEMENT:
input, integer
The
number of values to be deleted from a multi-value item. A value of -1 means to
delete all the values. The default is -1, i.e. to delete all the values.
- NRET:
output, integer
The
number of values actually deleted by the call to
x/zldel.
- HIST:
input, string
If
TYPE is 'HISTORY’ then this argument holds the name of the processing
task that identifies the particular history subset in which 'KEY' may be found;
if not entered, it defaults to the current task.
- INSTANCE:
input, integer
If
TYPE is 'HISTORY’ and HIST has been entered, INSTANCE gives the sequence
number of the particular instance of the processing task for the condition
where a processing task occurs more than once in the history subsets. If TYPE
is ‘PROPERTY’ and PROPERTY has been entered, INSTANCE gives the
sequence number of the particular instance of the property label for the
condition where a property set with identical names occurs more than once.
Default: 1.
- PROPERTY,
string: The name of the property set that the label routine is accessing The
PROPERTY optional argument is only valid if the type argument of the above
routines is set to “PROPERTY”. See
4.1.2.1
Using Property Labels,
for more information.
4.2.3 x/zlget—Return
the value of a label item
call xlget(unit, type, key, value, status, <optionals>, ' ')
status = zlget(unit, type, key, value, <optionals>, 0);
x/zlget
returns the value or values associated with a label item key word. VALUE may be
an array; the optional argument NELEMENT will indicate the dimension of VALUE.
Arguments:
- UNIT:
input, integer
Unit
of associated file.
- TYPE:
input, string
´PROPERTY',
'HISTORY' or 'SYSTEM'.
- KEY:
input, string
The
key word of the desired label item.
- VALUE:
output, array (size:NELEMENT) Receives the values of the label item. The type
of argument required depends on the FORMAT optional given. For single values,
INT returns an integer, REAL returns floating point (single-precision), and
STRING returns a simple string argument ( (char *) in C and CHARACTER in
FORTRAN). For multi-valued items (if NELEMENT is not 1), INT and REAL take
single-dimension arrays of integers or reals. ASTRING must be a two-dimensional
array of characters in either FORTRAN or C.
For
example, if you wanted to have a string array capable of handling 10 elements,
with 80 characters in each element, this is how you would declare it in C:
char value[10][80];
The
standard C null string terminator is always returned in the string, so the
above array could only hold 79 characters. You would still pass in the length
(via ULEN) as 80.
From
C, ULEN is required for multivalued strings (string arrays), as it specifies
the inner dimension of the array. For scalar strings (not an array), ULEN is
not strictly required as the length of the string is not required. BUT, you
will have no protection against overflowing the buffer. Specifying ULEN for a
scalar string ensures that an exceptionally long string value will not exceed
the size of your buffer. So it is a good idea to always specify ULEN from C,
although it's only really required for a string array.
In FORTRAN you use a CHARACTER array: CHARACTER*80 VALUE (10)
In
this case ULEN is not required, as the character descriptor contains the length
of each string. The space after the string itself is filled with blanks.
Optional
arguments:
- ERR_ACT:
input, string
Indicates
the action to be taken by the Executive when an error condition is raised as a
result of this call. A valid string may contain one or more of three characters
in any order, 'A', 'U', 'S'. The presence of each character has the following
meanings:
- A:
an error will cause an immediate program abort; otherwise, the routine will
return with an error number in STATUS
- U:
an error will cause the string that the user has specified with the ERR_MESS
optional to print
- S:
an error will cause a system message to print.
The
three values are independent of each other. Thus 'SA' will cause a system
message to be printed and the program to abort if an error occurs. If ERR_ACT
consists only of blanks, an error will cause routine to return an error number
in STATUS.
If
ERR_ACT is not specified, then the action defaults to the value of the LAB_ACT
optional to
x/zvopen
(the default for LAB_ACT is specified by
x/zveactiion).
- ERR_MESS:
input, string
Holds
the user message that the programmer wishes printed when an error occurs as
directed by ERR_ACT. Default is specified by
x/zveaction.
if the ERR_ACT option is not specified, and the LAB_ACT option given to
x/zvopen
specifies a message be printed, the message given by LAB_MESS,
not
ERR_MESS is printed.
- FORMAT:
input, format
Indicates
the format of the given label item value. Valid values are: 'INT', 'REAL',
‘DOUB’ and 'STRING'. The VALUE array type should match FORMAT, i.e.
float for REAL, double for DOUB, etc. See
Table 6: C Declarations for Run-Time Library Arguments)
for matching C declarations. See
Table 6: FORTRAN declarations for pixel types
for matching FORTRAN declarations.
In
the present implementation, FORMAT is required.
If
the format does not match the format of the currently existing label item, the
label item is changed to match what is given in this optional. If this is not
possible (i.e., a non-numeric string being changed to an integer), an error is
returned.
- INSTANCE:
input, integer
If
TYPE is 'HISTORY’ and HIST has been entered, INSTANCE gives the sequence
number of the particular instance of the processing task for the condition
where a processing task occurs more than once in the history subsets. If TYPE
is ‘PROPERTY’ and PROPERTY has been entered, INSTANCE gives the
sequence number of the particular instance of the property label for the
condition where a property set with identical names occurs more than once.
Default: 1.
- LEVEL:
output, integer
In
the ADD routine, which allows label items to be added to a label, a level may
be associated with a label item when that item is added. LEVEL returns the
positive integer which is the level of the label item. (NOT YET AVAILABLE)
- LENGTH:
output, integer
The
length of returned values. The length of 'INT' and 'REAL' formats is always 4.
The length of a string item is the length of the longest string element, not
including the null terminator (if present).
- ELEMENT:
input, integer
For
a multi-value item, the starting value to return into VALUE. Default: 1.
- NELEMENT:
input, integer
The
number of values to be returned of a multi-value item. A value of -1 means to
return all elements. The default is 1.
- NRET:
output, integer
The
number of values actually returned by the call to
x/zlget.
- HIST:
input, string
If
TYPE is 'HISTORY' then this argument holds the name of the processing task that
identifies the particular history subset in which 'KEY' may be found; if not
entered it becomes the current task.
- PROPERTY,
string: The name of the property set that the label routine is accessing The
PROPERTY optional argument is only valid if the type argument of the above
routines is set to “PROPERTY”. See
4.1.2.1
Using Property Labels,
for more information.
- ULEN:
input, integer
The
length of an input string. This optional only applies if the FORMAT is STRING.
For multi-valued items, ULEN is the maximum length of each string in the array,
i.e. it is the size of the first dimension of the array. ULEN is required in
some cases, and it is ignored in others. These are explained below.
There
are two ways to pass strings: C char and FORTRAN CHARACTER. See the VALUE
argument for an example of each.
- C:
If
NELEMENT is not 1 (multi-valued), then ULEN is required
.
If
NELEMENT is 1, then ULEN is optional. If present, it is used, otherwise the
length is the null-terminated length of the string.
- FORTRAN
CHARACTER:
ULEN
is
always ignored.
The
length is obtained from the character descriptor.
4.2.4 x/zlhinfo—Return
history label information
call xlhinfo(unit, tasks, instances, nhist, status, <optionals>, ' ')
status = zlhinfo(unit, tasks, instances, nhist, <optionals>, 0);
A
history label is partitioned into subsets, one for each processing task that
has 'read' or 'written' the data in the file described by the label.
x/zlhinfo
returns the names and instances of the history label subsets for the file
associated with UNIT.
Arguments:
- UNIT:
input, integer
The
unit number of the file described by the label of interest.
- TASKS:
output, string, fixed length 32 FORTRAN, 33 in C bytes
An
array of the task names in order of occurrence. At the present time the length
of a task name is still truncated to 8 ( only 8 are significant), but when
calling
x/zlhinfo
you should now provide a 32 character buffer (33 in C for the null terminator)
in order to accomodate future expansion.
- INSTANCES:
output, integer array
An
array with the same number of elements as TASKS giving the instance of each
task. If, for instance, the task A is the first third and sixth element in
TASKS, then INSTANCES (1)=1, INSTANCES (3)=2, and INSTANCES (6)=3.
- NHIST:
input/output, integer
On
input, it is the max dimension of TASKS and INSTANCES. On output, it is the
number of tasks in the current label.
- STATUS:
output, integer
The
error status. The values are listed in
10
Appendix B: Error Messages.
Optional
arguments:
- ERR_ACT:
input, string
Indicates
the action to be taken by the Executive when an error condition is raised as a
result of this call. A valid string may contain one or more of three characters
in any order, 'A', 'U', 'S'. The presence of each character has the following
meanings :
- A:
an error will cause an immediate program abort; otherwise, the routine will
return with an error number in STATUS
- U:
an error will cause the string that the user has specified with the ERR_MESS
optional to print
- S:
an error will cause a system message to print
The
three values are independent of each other. Thus 'SA' will cause a system
message to be printed and the program to abort if an error occurs. If ERR_ACT
consists only of blanks, an error will cause routine to return an error number
in STATUS.
If
ERR_ACT is not specified, then the action defaults to the value of the LAB_ACT
optional to
x/zvopen
(the default for LAB_ACT is specified by
x/zveaction).
- ERR_MESS:
input, string
Holds
the user message that the programmer wishes printed when an error occurs as
directed by ERR_ACT. Defaults is specified by
x/zveaction.
if the ERR_ACT option is not specified, and the LAB_ACT option given to
x/zvopen
specifies a message be printed, the message given by LAB_MESS,
not
ERR_MESS is printed.
- NRET
Returns
the total number of tasks in the label. This can differ from the NHIST argument
if the buffers provided were too small. NRET returns the total number of tasks
available, while NHIST returns the number actually in the buffers.
- ULEN
specifies the length of each element in the TASKS array. You can specify any
length (up to the maximum of 32 plus one for the terminator) for task names. In
FORTRAN, the FORTRAN string length is used. In C, the length comes from ULEN
(and defaults to 8 if ULEN is not given for backwards compatibility). Use a
ULEN of at least 9 from C, in order to get all 8 characters with a null
terminator.
4.2.5 x/zlinfo—Return
information about a single label item
call xlinfo(unit,type,key,format,maxlen,nelement,status,<optionals>,' ')
status = zlinfo(unit,type,key,format,maxlen,nelement,<optionals>, 0);
x/zlinfo
will return certain information about a single label item of given TYPE and KEY.
Arguments:
- UNIT:
input, integer
Unit
of associated file.
- TYPE:
input, string
´PROPERTY',
'HISTORY' or 'SYSTEM'.
- KEY:
input, string
The
key word of the desired label item.
- FORMAT:
output, string, maximum length 8
FORMAT
indicates the format of the label item. Valid values are: 'INT', 'REAL', or
'STRING'.
- MAXLENGTH:
output, integer
Indicates
the maximum length of any value associated with this key word. The length of
'INT' and 'REAL' items is always 4, meaning 4 bytes. The length of a 'STRING'
item does
not
include the null terminator, so if you are dynamically allocating an array in C
to hold the values, dimension it to MAXLENGTH + 1 to leave room for the null
terminator.
- NELEMENT:
output, integer
Returns
the number of values associated with the entered key word.
- STATUS:
output, integer
The
error status. The values are listed in
10
Appendix B: Error Messages.
Optional
arguments:
- ERR_ACT:
input, string
Indicates
the action to be taken by the Executive when an error condition is raised as a
result of this call. A valid string may contain one or more of three characters
in any order, 'A', 'U', 'S'. The presence of each character has the following
meanings:
- A:
an error will cause an immediate program abort; otherwise, the routine will
return with an error number in STATUS
- U:
an error will cause the string that the user has specified with the ERR_MESS
optional to print
- S:
an error will cause a system message to print
- The
three values are independent of each other. Thus 'SA' will cause a system
message to be printed and the program to abort if an error occurs. If ERR_ACT
consists only of blanks, an error will cause routine to return an error number
in STATUS.
If
ERR_ACT is not specified, then the action defaults to the value of the LAB_ACT
optional to
x/zvopen
(the default for LAB_ACT is specified by
x/zveaction).
- ERR_MESS:
input, string
Holds
the user message that the programmer wishes printed when an error occurs as
directed by ERR_ACT. Default is specified by
x/zveaction.
If
the ERR_ACT option is not specified, and the LAB_ACT option given to
x/zvopen
specifies a message be printed, the message given by LAB_MESS,
not
ERR_MESS is printed.
- MOD:
output, integer
Indicates
whether the label item is modifiable by the programmer. Values: 0 modifiable, 1
not modifiable. (NOT YET AVAILABLE)
- STRLEN:
output, integer
This
optional returns the maximum length of any label element when the elements are
treated as strings. For STRING format labels, this is identical to MAXLENGTH.
For INT or REAL formats, the label is treated as if the integer or real values
were strings, and the length of the character representation of the value is
returned. This is needed in combination with calling
x/zlget
with a FORMA T of STRING, which causes all items to be returned as strings.
This is useful when printing the values, as no format conversion is required.
- INSTANCE:
input, integer
If
TYPE is 'HISTORY’ and HIST has been entered, INSTANCE gives the sequence
number of the particular instance of the processing task for the condition
where a processing task occurs more than once in the history subsets. If TYPE
is ‘PROPERTY’ and PROPERTY has been entered, INSTANCE gives the
sequence number of the particular instance of the property label for the
condition where a property set with identical names occurs more than once.
Default: 1.
- HIST:
input, string
If
TYPE is 'HISTORY' then this argument holds the name of the processing task that
identifies the particular history subset in which 'KEY' may be found; if not
entered, defaults to current task.
- PROPERTY,
string: The name of the property set that the label routine is accessing The
PROPERTY optional argument is only valid if the TYPE argument of the above
routines is set to “PROPERTY”. See
4.1.2.1
Using Property Labels,
for more information.
4.2.6 x/zlninfo—Return
name of next key
call
xlninfo(unit,key,format,maxlength,nelement,status,<optionals>,' ')
status
= zlninfo(unit,key,format,maxlength,nelement,<optionals>, 0);
x/zlninfo
operates much like the routine
x/zlinfo
except that
x/zlninfo
does not expect an input for KEY. Instead,
x/zlninfo
will return a string in KEY which holds the next label item key word in the
sequence of label items for the given TYPE. In addition,
x/zlninfo
will return the same information as
x/zlinfo.
If the last available label item has already been returned then that condition
will be indicated in STATUS.
Arguments:
- UNIT:
input, integer
Unit
of associated file.
- KEY:
output, string, maximum length 32
The
key word of the next label item.
- FORMAT:
output, string, maximum length 8
Indicates
the format of the label item. Values: 'INT', 'REAL', 'STRING'.
- MAXLENGTH:
output, integer
Indicates
the maximum length of any value associated with this key word. The length of
'INT' and 'REAL' items is always 4, meaning 4 bytes. The length of a 'STRING'
item does
not
include the null terminator, so if you are dynamically allocating an array in C
to hold the values, dimension it to MAXLENGTH + 1 to leave room for the null
terminator.
- NELEMENT:
output, integer
Returns
the number of values associated with the entered key word.
- STATUS:
output, integer
The
error status. The values are listed in
10
Appendix B: Error Messages.
Optional
arguments:
- ERR_ACT:
input, string
Indicates
the action to be taken by the Executive when an error condition is raised as a
result of this call. A valid string may contain one or more of three characters
in any order, 'A', 'U', 'S'. The presence of each character has the following
meanings:
- A:
an error will cause an immediate program abort; otherwise, the routine will
return with an error number in STATUS
- U:
an error will cause the string that the user has specified with the ERR_MESS
optional to print
- S:
an error will cause a system message to print
- The
three values are independent of each other. Thus 'SA' will cause a system
message to be printed and the program to abort if an error occurs. If ERR_ACT
consists only of blanks, an error will cause routine to return an error number
in STATUS.
If
ERR_ACT is not specified, then the action defaults to the value of the LAB_ACT
optional to
x/zvopen
(the default for LAB_ACT is specified by
x/zveaction).
- ERR_MESS:
input, string
Holds
the user message that the programmer wishes printed when an error occurs as
directed by ERR_ACT. Default is specified by
x/zveaction.
If
the ERR_ACT option is not specified, and the LAB_ACT option given to
x/zvopen
specifies a message be printed, the message given by LAB_MESS,
not
ERR_MESS is printed.
- MOD:
output, integer
Indicates
whether the label item is modifiable by the programmer. Values: 0 modifiable, 1
not modifiable. (NOT YET AVAILABLE)
- STRLEN:
output, integer
This
optional returns the maximum length of any label element when the elements are
treated as strings. For STRING format labels, this is identical to MAXLENGTH.
For INT or REAL formats, the label is treated as if the integer or real values
were strings, and the length of the character representation of the value is
returned. This is needed in combination when calling
x/zlget
with a FORMAT of STRING, which causes all items to be returned as strings. This
is useful when printing the values, as no format conversion is required.
4.2.7 x/zlpinfo—Returns
the names of property subsets in the given file
call xlpinfo(unit, properties, nprop, status, <optionals>, ' ')
status = zlpinfo(unit, properties, nprop, <optionals>, 0);
Returns
the names of property subsets in the given file. Property labels are broken up
into subsets, each with a property name. This routine returns a list of all
property names in the file specified by UNIT, which must be open. This routine
is identical to
xlhinfo,
except that it returns property names instead of task names and instances.
Arguments:
- UNIT:
integer, input
UNIT
is the unit number of an open file. The property names in the property label of
this file are returned.
- PROPERTIES:
string array, output
PROPERTIES
is a string array that gets the list of property names. When
x/zlpinfo
is called from C, the size of each string in the array is given by the ULEN
optional argument (which is required from C). There is no 8-character default
as there is in
zlhinfo.
From FORTRAN, ULEN is optional, since the string length is obtained from the
array itself (which must be a CHARACTER*n array). Since property names can be
up to 32 characters, you should declare a FORTRAN array to be at least
CHARACTER*32, and a C array should be at least 33 characters long (one
additional character for the null terminator). The number of strings in the
array is specified by the NPROP argument.
- NPROP:
integer, input/output
On
input, NPROP is the major dimension (maximum number of strings) in PROPERTIES.
On output, it returns the number of properties returned in PROPERTIES. If there
are more properties than the input NPROP allows, then the returned NPROP will
be the same as the input since the maximum number of properties are returned.
If you want the total number of properties in the label, regardless of the size
of your supplied buffer, use the NRET optional argument.
- STATUS:
output, integer
The
error status. The values are listed in
10
Appendix B: Error Messages.
Optional
Arguments:
- ERR_ACT:
string, input
Indicates
the action to be taken by the RTL when an error occurs in this routine. A valid
string may contain one or more of the characters listed below, in any order.
- A
: Abort the program on error; otherwise the routine returns with STATUS set.
- U
: Print the string specified in ERR_MESS if an error occurs.
- S
: Print a system error message describing the error.
The
three values are independent of each other. Thus, “SA” will cause a
system error message to be printed and the program to abort if an error occurs.
If ERR_ACT is empty or contains only blanks, no action will be taken on error,
and the error code will be returned in STATUS.
If
ERR_ACT is not specified, then the action defaults to the value of the LAB_ACT
optional to
x/zvopen
.
The default for LAB_ACT is specified by
x/zveaction.
- ERR_MESS:
string, input
Specifies
the user message to be printed when an error occurs as directed by ERR_ACT. If
the ERR_ACT option is not specified, and the LAB_ACT option given to
x/zvopen
specifies that a message be printed, the message given by LAB_ACT,
not
ERR_MESS, is printed.
- NRET,
integer, output
NRET
returns the total number of properties in the label. This can differ from the
NPROP argument if the buffer provided was too small. NPROP returns the number
actually in the buffer, while NRET returns the total number available.
- ULEN,
integer, input
ULEN
specifies the length of each element in the PROPERTIES array. ULEN is required
on
x/zlpinfo
when called from C to define the inner dimension of the array. Make sure to
leave space for the null terminator, so ULEN should be at least 33. From
FORTRAN, ULEN is optional. If it is not given, the string length will be picked
up from the string array itself. The CHARACTER*n variable should be at least 32
characters.
- INST_NUM,
integer array, output.
An array with the same number of elements as NPROPS giving the instance of each
property. INST_NUM returns a list of instances that match the names already
returned. For example, if the property A is the first third and sixth element
in PROPERTIES, then INST_NUM (1)=1, INST_NUM (3)=2, and INST_NUM (6)=3. If
INST_NUM is not supplied, you won't get instance numbers, but you will still
get repeated occurrences of names in the property name list if multiple
instances are present.