LMPUT—write a logical record to a data set

The LMPUT service writes one logical record to the data set associated with a given data ID. The first LMPUT writes the first logical record to the data set, and later invocations write succeeding records. The LMINIT service with ENQ(EXCLU), ENQ(SHRW), ENQ(MOD), and the LMOPEN service with the OUTPUT option must be completed before you can use the LMPUT service.

If the data set is an ISPF library or MVS™ partitioned data set, the LMMADD or LMMREP service must be invoked after the last LMPUT to update the directory and to write the last physical record.

If the data set is sequential, the LMCLOSE service must be invoked after the last LMPUT to write the last physical record and to close the data set.

When MODE(MULTX) is used, the write 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 written is 32 000 bytes. LMPUT requires data in the dataloc-var to be in this format:

+------+--------------+------+--------------+------+--------------+
|len   | record       |len   | record       |len   | record       |
+------+--------------+------+--------------+------+--------------+
<----     data-length should be set to this length             --->
<----     if less than, then fewer records are written         --->
<----     if greater than, then data-length is ignored         --->

The LMPUT service writes records to a data set as is. That is, the LMPUT service does not pack data before writing it if the data is in unpacked format. In order to pack data before writing it, use Edit with the pack option.

Command invocation format


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

>--DATALOC(dataloc-var)--DATALEN(data-length)--+---------+-----><
                                               '-NOBSCAN-'

Call invocation format


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

>--,dataloc-var--,data-length--,'b'--,--+-'NOBSCANb'-+--);-----><
                                        '-'b'--------'


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

Parameters

data-id: The data ID associated with the data set into which the record is to be written. The data ID has been generated by the LMINIT service. The maximum length of this parameter is 8 characters.
INVAR|MOVE|MULTX: In INVAR mode and MULTX mode, the data-location parameter variable contains the data itself. In MOVE mode, the data-location parameter contains the address of the data to be written. A command dialog can use INVAR and MULTX modes, but not MOVE mode.
dataloc-var: The name of a variable that, on entry to the LMPUT service, contains either the data to be written (INVAR or MULTX mode) or the fullword binary virtual storage address of the data to be written (MOVE mode).
The value of the variable passed from a program function can be either the data record itself or the address of the data record, but it must be consistent with the INVAR|MOVE|MULTX specification. If the variable was passed from a command function written in CLIST or REXX, it must always contain the data record. The maximum length of this parameter is 8 characters.
data-length: The length in bytes of the logical record to be written. The parameter must be a positive nonzero integral value. If the data-length specification causes a DBCS character string to be divided in the middle, the result may be unpredictable.
In MULTX mode, the minimum of the data-length parameter and the length of data written to the variable pool determines how much of the data-loc variable is processed into records. The length field before each record determines the amount of data written, not exceeding the data set record length, to each record.
NOBSCAN: The No Backscan option; no truncation of trailing blanks for records of variable length occurs.
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.

10

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

12

Either:

The data set is not open or is not open for output.
The parameter value is invalid.

16

Truncation or translation error in accessing dialog variables.

20

Severe error; unable to continue.

Example

This example invokes the LMPUT service to write a data record, with a length of 80 bytes, contained in variable DATAVAR into the data set associated with the data ID in variable DDVAR.

Command invocation

ISPEXEC  LMPUT DATAID(&DDVAR)   MODE(INVAR)     +
               DATALOC(DATAVAR) DATALEN(80)

Call invocation

DATALEN=80;
CALL ISPLINK('LMPUT',DDVAR,'INVAR ','DATAVAR ',DATALEN);
Where DATALEN is a fullword integer variable.

OR

Set the program variable BUFFER to contain:

BUFFER = 'LMPUT DATAID(&DDVAR)   MODE(INVAR)
                DATALOC(DATAVAR) DATALEN(80)';

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

CALL ISPEXEC (BUFLEN, BUFFER);

Note: Null variables must be defined to have a length greater than zero. Programs containing definitions of null variables must specify VDEFINE with the NOBSCAN option. Null variables defined in CLISTs should be initialized with the &STR built-in function. Null variables defined in REXX should be initialized by setting them to ' '. For example, if x is the name of a variable: x = ' '

Example (MULTX)

This REXX example invokes the LMPUT service to process a data set in MULTX mode, writing blocks of data in segments no larger than 32 000 bytes. LMPUT pads records that are too short with blanks and truncates records that are too long for the target data set.

  /* REXX to write out some data to a VB dataset */
   REC = ''
   DLEN = 0
   DO I = 1 TO 100
     X = 5 * I
     A = 'DATA LINE 'I' '
     DO J = 1 TO X
       A = A || 'D'
     END
     RLEN = LENGTH(A)
     NLEN = DLEN + RLEN + 2
     IF NLEN > 32000 THEN DO
        /* WRITE CURRENT BUFFER BEFORE IT GETS TOO BIG */
        'LMPUT DATAID('TESTFILE') MODE(MULTX) DATALOC(REC) ,
        DATALEN('DLEN')'
        IF RC > 0 THEN I = 1000
        REC = ''
        DLEN = RLEN + 2
     END
     ELSE DLEN = NLEN
     RLEN = D2C(RLEN,2)
     REC = REC || RLEN || A
   END
   /* WRITE LAST BUFFER */
   'LMPUT DATAID('TESTFILE') MODE(MULTX) DATALOC(REC) ,
    DATALEN('DLEN')'