IFGETV (HLI function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
Line 1: Line 1:
The conventions used on this page are described in [[HLI: Function call list#Function call notation conventions|Function call notation conventions]].
The conventions used on this page are described in [[HLI: Function summary#Function call notation conventions|Function call notation conventions]].


==Summary==
==Summary==

Latest revision as of 23:04, 12 July 2016

The conventions used on this page are described in Function call notation conventions.

Summary

Description
The IFGETV call (GET VALUE) extracts the next field value from the current value set and returns the specified data to the user.
Thread type
single cursor IFSTRT
IFCALL function number
77

Syntax

IFGETV(RETCODE,BUFFER,EDIT_SPEC,GETV_NAME)

Compile-only form
IFCALL function number: 78

IFGTVC(RETCODE,EDIT_SPEC,GETV_NAME)

Execute-only form
IFCALL function number: 79

IFGTVE(RETCODE,BUFFER,GETV_NAME)

Specify the parameters in the syntax order shown above.

Parameter Description
RETCODE [O,i,r] The Model 204 return code is the required first parameter. The code is a binary integer value.
BUFFER [O,c,r] The buffer location is a required output parameter which specifies the address of the user's data area. The buffer contains the data returned by IFGETV as defined by the EDIT_SPEC parameter, described below. Specify a character string.
EDIT_SPEC [I,c,r] The edit specification is a required input parameter which defines the format of the data to be returned from the specified value. The specification describes the format of the data which is returned at the buffer location (see BUFFER above). Specify a character string using either of the following LIST or EDIT format options:

LIST; EDIT (edit format);

where:

edit format is required in the EDIT specification and specifies a code or codes indicating the format of the data to be returned for the current value.

See HLI: Field formatting options for HLI calls for a description of LIST, DATA, and EDIT formatting.

GETV_NAME

[I,s,r/o] The name of the IFGETV compilation is an input parameter that is only required if using the Compiled IFAM facility (IFGTVC and IFGTVE). Model 204 saves the compilation using this name. Specify the name as unique, and as a short character string. any characters except the following are valid in the name: blank, comma, parenthesis, equal sign, or semicolon. A null value is equivalent to omitting the name parameter.

Usage notes

Use IFGETV to retrieve the next value from the current set.

IFGETV is used to extract one field value from the value set built by IFFDV or IFSRTV.

Completion return code (RETCODE)

IFGETV must be called after IFFDV is called. Otherwise, Model 204 returns an error code of 2, which indicates that no value exists in the current set. Note that an error code of 2 may also indicate that the current set has been exhausted.

Coding example (Assembler)

The following z/OS ASSEMBLER example provides an IFGETV call. In the example, IFFDV has been called first to find all the values of field COLOR:

. . . CALL IFGETV,(RETCODE,DATA,SPEC),VL . . . RETCODE DC F'0' DATA DC CL256' ' * SPEC DC C'LIST;' *

In this example, if you specify LIST; the retrieved data appears in the data area with single quotation marks, for example, `RED'. Or, if you specify EDIT as shown in the example below, the retrieved data appears in the data area without quote marks, that is, as RED.

* SPEC DC C'EDIT (A(3));'