IFMOREX (HLI function)

From m204wiki
Revision as of 23:06, 12 July 2016 by ELowell (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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

Summary

Description
The IFMOREX call (MORE EXCLUSIVE) continues the IFGETX function to retrieve more data from the current record, enqueuing on the record in exclusive mode.
Thread type
single cursor IFSTRT
IFCALL function number
37

Syntax

IFMOREX|IFMREX(RETCODE,BUFFER,EDIT_SPEC,TIME,MOREX_NAME,%VARBUF,%VARSPEC)

Compile-only form
Not available. You can use the IFMOREC form of IFMORE.
Execute-only form
IFCALL function number: 53

IFMORXE|IFMRXE(RETCODE,BUFFER,MOREX_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 IFMORE for the fields that are defined by the EDIT_SPEC parameter, described below. Specify a character string.

Note: The data is placed in the data area from left to right. If parameters are being passed without dope vectors (IFSTRT language indicator = 2), the data is placed in the area as specified. No length checking is attempted because the Host Language Interface does not know the length of the data area.

EDIT_SPEC [I,c,r] The edit specification is a required input parameter that defines the fields 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.
MOREX_NAME [I,s,r/o] The name of the IFMOREX compilation is an input parameter that is only required if using the Compiled IFAM facility (IFMORXE). 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 it 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.

Usage notes

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

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

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

Coding example (COBOL)

WORKING-STORAGE SECTION. 01 ARGS-FOR-CALL. 05 RETCODE PIC 9(5) COMP SYNC. 05 WORK-AREA-1 PIC x(256). 05 WORK-AREA-2 PIC X(256). . . . 01 SPEC-1 PIC X(64) VALUE 'EDIT (SSN,NAME,BDATE,SCDATE,GRADE,STEP) (A(9),A(30),2A(6),2J(2));'. 01 SPEC-2 PIC X(34) VALUE 'EDIT (STATUS,SALARY)(A(11),A(12));'. 01 TIME PIC 9(5) COMP SYNC VALUE 5. . . . PROCEDURE DIVISION. . . . CALL "IFGET" USING RETCODE, WORK-AREA-1, SPEC-1 IF GRADE IS EQUAL TO 9 THEN PERFORM GETMORE. . . . GETMORE. CALL "IFMOREX" USING RETCODE, WORK-AREA-2, SPEC-2, TIME.