LMGET—read a logical record from a data set

The LMGET service reads one logical record from the data set associated with the given data ID. Completion of the LMINIT and LMOPEN services for the data set is required before LMGET is invoked.

If the data to be processed is a sequential data set, the first LMGET reads the first logical record. Later invocations read successive logical records; that is, the second invocation reads the second logical record, the third invocation reads the third logical record, and so on.

If the data is an ISPF library or MVS™ partitioned data set, previous completion of the LMMFIND service is required in addition to completion of LMINIT and LMOPEN. The LMGET service reads from the last member referred to by the LMMFIND service in the data sets being processed. Thus, if LMMFIND is issued referencing member A, LMGET reads from member A. If another LMMFIND is issued referencing member B, LMGET reads from member B, not member A.

When MODE(MULTX) is used, the read operation occurs in segments (rather than in single records), with each segment comprising multiple records. Each record is prefixed by a 2-byte binary integer field containing its length. The maximum size of each segment returned is 32 000 bytes. LMGET returns data to the dataloc-var in this format:

+------+--------------+------+--------------+------+--------------+
|len   | record       |len   | record       |len   | record       |
+------+--------------+------+--------------+------+--------------+
<-----     this length is returned in datalen-var             ---->

The data read is always unpacked. If the data set contains packed data, LMGET unpacks the data.

Command invocation format


>>-ISPEXEC--LMGET--DATAID(data-id)--MODE(-+-MOVE---+-)---------->
                                          +-LOCATE-+     
                                          +-INVAR--+     
                                          '-MULTX--'     

>--DATALOC(dataloc-var)--DATALEN(datalen-var)------------------->

>--MAXLEN(max-length)------------------------------------------><

Call invocation format


>>-CALL--ISPLINK--('LMGETbbb'--,data-id--,-+-'b'---------+------>
                                           +-='MOVEbbbb'-+   
                                           +-'LOCATEbb'--+   
                                           +-'INVARbbb'--+   
                                           '-'MULTXbbb'--'   

>--,dataloc-var--,datalen-var--,max-length);-------------------><


>>-CALL--ISPEXEC--(buf-len,--buffer);--------------------------><

Parameters

data-id: The data ID associated with the data set to be read. The data ID has been generated by the LMINIT service. The maximum length of this parameter is 8 characters.
MOVE|LOCATE|INVAR|MULTX: Whether the data is to be moved, located, or stored into an ISPF dialog variable, and whether the data should be read in single records (default) or in segments containing multiple records (MULTX). A calling program function can specify any mode, with information being passed through the data location variable. A command dialog can use INVAR and MULTX modes, with data being returned to the command in the data location variable.
dataloc-var: The name of the data location variable. In MOVE mode, the variable contains a binary virtual storage address at which the data read by LMGET is to be stored. In LOCATE mode, the address of the data read by LMGET is placed in the data location variable. In INVAR and MULTX modes, the data read by LMGET is itself placed in the data location variable. The maximum length of this parameter is 8 characters.
datalen-var: The name of the variable into which LMGET stores the actual length of the record read. In MULTX mode ISPF stores the length of data returned in the datalen-var. The maximum length of this parameter is 8 characters.
max-length: A fullword binary integer containing the maximum record length to be read in bytes. This parameter must be a nonzero positive integer value. In MOVE mode, the value is the maximum number of bytes of data to be moved. In INVAR mode, the value is the maximum number of bytes of data to be stored in the data location variable. The value is not changed by LMGET in either mode. In MULTX mode, the value is the maximum number of bytes to be stored from each record read, to make up the segment that will be stored in the data location variable. The parameter is ignored in LOCATE mode. If the max-length specification causes a DBCS character string to be divided in the middle, the result may be unpredictable.
buf-len: A fullword fixed binary integer containing the length of the buffer parameter.
buffer: A buffer containing the name of the service and its parameters in the same form as they would appear in an ISPEXEC invocation for a command invocation.

Return codes

These return codes are possible:

0

Normal completion.

8

End-of-data set condition; no message formatted.

10

No ISPF library or data set associated with the given data ID; that is, LMINIT has not been completed.

12

One of these:

The data set is not open or is not open for input.
An LMMFIND was not done for a partitioned data set.
The parameter value is invalid.

16

A truncation or translation error occurred in accessing dialog variables.

20

Severe error; unable to continue.

Example 1

This example invokes the LMGET service to read a record from the data set associated with the data ID in variable DDVAR, in INVAR mode, with LOCVAR as the data location variable, LENVAR as the actual record length variable, and 80 bytes as the maximum record length.

Command invocation

ISPEXEC LMGET DATAID(&DDVAR)  MODE(INVAR) DATALOC(LOCVAR)  +
              DATALEN(LENVAR) MAXLEN(80)

Call invocation

MAXLEN=80;
CALL ISPLINK('LMGET   ',DDVAR,'INVAR   ','LOCVAR ','LENVAR ',MAXLEN);

MAXLEN is a fullword integer variable.

OR

Set the program variable BUFFER to contain:

BUFFER = 'LMGET DATAID(&DDVAR)  MODE(INVAR) DATALOC(LOCVAR)
               DATALEN(LENVAR) MAXLEN(80)';

Set the program variable BUFLEN to the length of the variable BUFFER. Issue the command:

CALL ISPEXEC (BUFLEN, BUFFER);

Example 2

This example initializes and opens an input and an output data set, using LMINIT and LMOPEN respectively. The exec loops through the all the records of the input data set using the LMGET service. Each record of the input data set is stored into the variable srchline. The variable srchline is parsed to find a member name. The string 'SELECT ' followed by the member name is stored into a variable called selline which is added to the output data set, using the LMPUT service. The input and output data sets are closed and freed using LMCLOSE and LMFREE.

/* rexx *************************************************************/
/*                                                                  */
/* Member:  SETSRCH                                                 */
/*                                                                  */
/* Purpose: To create a srchfor.stmts data set that contains        */
/*          only those members with a certain string. For example,  */
/*          if both CLIST and REXX execs are stored in the same     */
/*          library, but you only want to search the REXX members   */
/*          search the library for the word rexx, with the options  */
/*          listed below to create srchfor.list. Use the resulting  */
/*          statements data set as input to the next search.        */
/*                                                                  */
/* Setup:   Create the srchfor output using option 3.15 with        */
/*          process options:                                        */
/*             LMTO NOSUMS NOPRTCC                                  */
/*          to create an output listing data set called             */
/*          userid.srchfor.list without a summary section or page   */
/*          dividers.                                               */
/*                                                                  */
/* Input:   userid.SRCHFOR.LIST (as created in setup).              */
/*                                                                  */
/* Output:  userid.SRCHFOR.STMTS containing a SELECT statement      */
/*          for each member to be searched.                         */
/*                                                                  */
/********************************************************************/
address ispexec
'lminit dataid(srchout) dataset(srchfor.list) enq(shr) '
if rc = 0 then
  do
    'lmopen dataid('srchout') option(input)'
    if rc = 0 then
      do
        'lminit dataid(srchstmt) dataset(srchfor.stmts) enq(exclu)'
        if rc = 0 then
          do
            'lmopen dataid('srchstmt') option(output)'
            if rc = 0 then
              do
                done = 'n'
                datavar = 0
                linenum = 1
                do while done = 'n'
                  'lmget dataid('srchout') mode(invar) dataloc(srchline)
                     datalen(datavar) maxlen(132)'
                   if rc = 0 then
                     do
                       linenum = linenum + 1
                       if linenum > 5 then   /* skip over header */
                         do
                           parse var srchline memname linesfnd linesrch
                           if memname /= ' ' then
                             do
                               selline = 'SELECT ' memname
                               'lmput dataid('srchstmt') mode(invar),
                                  dataloc(selline) datalen(80)'
                               if rc > 0 then
                                 done = 'y'
                             end
                         end
                     end
                   else
                     done = 'y'
                 end
                 'lmclose dataid('srchstmt ')'
              end
            'lmfree dataid('srchstmt ')'
          end
        'lmclose dataid('srchout ')'
      end
    'lmfree dataid('srchout ')'
  end
exit

Example 3 (MULTX)

This REXX example invokes the LMGET service to process a data set in MULTX mode, returning blocks of data in segments no larger than 32 000 bytes. The data set has a record length of 80 bytes in this example, but for variable data the length will vary and must be calculated as shown:

  /* REXX */
   ADDRESS ISPEXEC;
   'LMGET DATAID('DDVAR') MODE(MULTX) DATALOC(REC) DATALEN(DLEN) ,
    MAXLEN(80)'
   GETRC = RC
   DO FOREVER
     INDEX = 1
     DO WHILE INDEX < DLEN
       LEN = SUBSTR(REC,INDEX,2)
       LEN = C2D(LEN)
       IF LEN > 0 THEN CALL process_record
       INDEX = INDEX + LEN + 2
     END
     IF GETRC = 0 THEN DO
       'LMGET DATAID('DDVAR')' MODE(MULTX) DATALOC(REC) ,
       DATALEN(LEN) MAXLEN(80)'
       GETRC = RC
     END
     ELSE LEAVE
   END