IFGETX (HLI function)

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

Summary

Description

The IFGETX call (GET EXCLUSIVE) retrieves the next logical record from the current set, enqueuing on the record in exclusive mode, and returns the specified fields.

Thread type

single cursor IFSTRT

IFCALL function number

36

Syntax

IFGETX(RETCODE,BUFFER,EDIT_SPEC,TIME,GETX_NAME,%VARBUF,%VARSPEC,ORD_SPEC)

Compile-only form

Not available. You can use the IFGETC form of IFGET.

Execute-only form

IFCALL function number: 50

IFGETXE|IFGTXE(RETCODE,BUFFER,TIME,GETX_NAME,%VARBUF,%VARSPEC)

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 that specifies the address of the user's data area. The buffer contains the data returned by IFGETX for the fields that are 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 that defines the fields that are to be returned from the specified record. The specification describes the format of the data that is returned at the buffer location (see BUFFER above). Specify a character string using one of the following LIST, DATA, or EDIT format options: LIST (fieldname list); DATA (fieldname list); DATA; EDIT (fieldname list) (edit formats); EDIT (fieldname list1) (edit format1) (fieldname list2) (edit format2); where: fieldname list is required and specifies a field name or names. Specify elements in the field name list using one of the following options: fieldname fieldname (n) fieldname(*) fieldname(%variable) where: fieldname retrieves the first occurrence of the named field. fieldname(n) retrieves the nth occurrence of the named field. fieldname(*) retrieves all occurrences of the named field in the order of occurrence. fieldname(%variable) retrieves the occurrence of the field specified by the %VARBUF and %VARSPEC parameters. 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 named field in the fieldname list-edit format pair. See HLI: Field formatting options for HLI calls for a description of LIST, DATA, and EDIT formatting.
TIME	[I,i,r] The time is a required input parameter. Specify an integer value that is the number of times to try the retrieval in the event of an enqueuing conflict; the wait time is in three-second periods.
GETX_NAME	[I,s,r/o] The name of the IFGETX compilation is an input parameter that is only required if using the Compiled IFAM facility (IFGETXE). 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.
%VARBUF	[I,c,o] The variable buffer is an optional input parameter that addresses a data area which accommodates up to 255 bytes of data per value. The buffer contains values that are defined by the %VARSPEC parameter, below, to be assigned to %variables. Specify a character string. For information about %variables, see Using variables and values in computation.
%VARSPEC	[I,c,o] The variable specification describes the format of the data that is contained in the %variable parameter, and lists the %variables to be assigned. %VARSPEC specifies the contents of the variable buffer, described above. Specify a character string that follows a LIST, DATA, or EDIT syntax. %VARSPEC is a required input parameter if %VARBUF is specified.
ORD_SPEC	[I,c,o] The order specification is an optional input parameter that provides ordered index functionality. The order specification specifies the ORDERED index field that is used to order the return of the records. Specify the order using an IN ORDER clause, such as is used with IFGET. See ORD_SPEC for a description of the order specification used for IFGET that is also valid for IFGETX. Note: The order specification is interpreted only on the first IFGETX call following an IFFIND. Thereafter, it is only necessary to provide the first seven parameters on subsequent IFGETX calls for the same IFFIND. If you use the order specification parameter, all eight parameters must be coded, even if some contain dummy parameters. For more information about the order specification, see Record loops.

Usage notes

Use IFGETX to retrieve the next record from the current set. Only fields that you specify are returned to the application program.

IFGETX performs the same operations as IFGET. However, the record is enqueued upon in exclusive rather than in share status.

Use IFGETX if several users share a file and extensive processing is to be done between the IFGET which retrieves the record and an update operation on the record.

If a call to IFGETX results in an enqueuing conflict, Model 204 waits at most three seconds and then tries again, for as many time as specified in the time parameter (the wait time is in 3-second periods).

After trying unsuccessfully for the number of times specified in the time parameter, Model 204 returns a completion code of 3 to the HLI program. For more information, see ENQRETRY parameter.

Coding example (COBOL)

01 RETCODE PIC 9(5) COMP SYNC. 01 WORK-REC. 05 WORK-SSN PIC 9(9). 05 WORK-NAME PIC X(30). 05 WORK-BDATE PIC 9(6). 05 WORK-SCDATE PIC 9(6). 05 FILLER PIC X(2). 05 WORK-GRADE PIC 9(2). 05 WORK-STEP PIC 9(2). . . . 01 TIME PIC 9(5) COMP SYNC VALUE 5. 01 EDITLIST-1 PIC X(68) VALUE 'EDIT(SSN,NAME,BDATE,SCDATE,GRADE,STEP)(A(9), - A(30),2A(6),'X(2),2J(2));'. . . . CALL 'IFGETX' USING RETCODE, WORK-REC, EDITLIST-1, TIME. . . .