PIPE QSAM

Syntax

QSAM
Read syntax diagramSkip visual syntax diagramQSAM (DD) (DSN) data_set_name data_definition_name APPEND

Synonyms

Stage Name Synonym
QSAM (read) <
QSAM (write) >
Note: The < and > synonyms for QSAM read and write can only be used when < and > are immediately followed by a data set name enclosed in quotation marks. The < synonym has additional functionality as the < (from disk) stage. See HELP PIPE < and HELP PIPE > for more information. See PIPE < (From Disk) and PIPE > (To Disk) for more information.

Command Description

The QSAM stage reads and writes from dynamically allocated data definition names or data sets. Other devices are also supported when allocated for Physical Sequential access.

The QSAM stage can be used with either a data definition name defined by the ALLOCATE command, or a fully qualified data set name. If desired, a data set name can be enclosed in single quotation marks. The quotation marks are ignored.

When specified as a first stage to read a file, QSAM reads from the data definition name or data set. When not specified as a first stage, QSAM writes to the data definition name or data set. The messages received on the input stream are passed to the output stream.

Streams

Stream Type Number Supported
Input 1
Output 2

Termination Conditions

When specified as a first stage to read a file, the QSAM stage terminates when end-of-file is reached or when the output stream is disconnected. When not a first stage, QSAM terminates when the input stream is disconnected.

A signed 10-digit decimal return code is written to the secondary output stream if the secondary stream is connected.

Operand Descriptions

data definition name
Specifies what data definition name is to be used. If an initial (DD) or (DSN) is not specified, the QSAM stage examines the specification. If the argument is a single 1- to 8-character value without period delimiters or quotation marks, then it is considered a data definition name. Otherwise, the argument is considered a data set name.

You can use a data definition name with the QSAM stage by executing an ALLOCATE command. A data set allocated in this manner can include a member name as part of the specification. A data definition name that is specified to QSAM with a member name is rejected. When using this method for a device or medium that is not a data set, it must be suitable for Physical Sequential access. Specify DSORG(PS) and a suitable block size.

data set name
Specifies what data set name is to be used. If an initial (DD) or (DSN) is not specified, the QSAM stage examines the specification. If the argument is a single 1- to 8-character value without period delimiters or quotation marks, it is considered a data definition name. Otherwise, the argument is considered a data set name.
(DD)
Specifies that the specification is for a data definition.
(DSN)
Specifies that the specification is for a data set name.
APPEND
Specifies that the data is to be appended onto the end of the records that are already in the file (otherwise writing generally occurs from the start). APPEND causes the DCB to be opened internally with the EXTEND option. Another method for appending onto the end is to allocate the file using the MOD keyword, in which case the QSAM APPEND option is redundant. See the ALLOCATE command in the NetView® online help or IBM Z® NetView Command Reference Volume 1 (A-N).

Do not use the APPEND option when writing to a PDS member.

Usage Notes

  • QSAM cannot access a data definition name and member name combination except through a DDNAME allocated with a member name.
  • When neither DD or DSN is specified, the QSAM stage examines the name specification to determine whether it is a data set name or a data definition name. This is the default.
  • You can read and write to the same data definition or data set name within a single pipe.
  • Access security for the QSAM stage is provided through the READSEC and WRITESEC commands. See the IBM Z NetView Administration Reference for information on the READSEC and WRITESEC commands. Other errors can stop processing before the security check can be done.
  • The QSAM stage allocates the data set with DISP=SHR specified and then opens the data set requesting OUTPUT access. It is possible for another application or task to be writing or reading the data set at the same time as the PIPE QSAM stage is reading or writing the data set. You might encounter this restriction when two different QSAM stages are attempting to write to different members of the same PDS. When this situation occurs, the QSAM stage issues message DSI084I and a return code of 16. In this case, the system issues the message "IEC143I 213-30".
  • If you omit the FILE operand, a unique ddname with a name of SYSnnnn is assigned by dynamic allocation and then returned in the CNM272I message. Do not specify the FILE operand unless a specific ddname must be allocated. This prevents allocations failing because of ddname conflicts. It also prevents problems caused by deallocating a data set that is shared by multiple NetView tasks. Each NetView task must allocate the file with a unique ddname. If one task deallocates its ddname, the other tasks do not lose their access to the file.
  • If you allocate a partitioned data set as an input data set and specify a member name that does not exist, the ALLOCATE command completes successfully with a return code of 0. However, you receive an OPEN error when you attempt to open the data set for input.
  • Allocate the files with the FREE operand whenever possible. The files are then deallocated automatically when they are closed. This reduces virtual storage use. There is also an MVS™ limit of 1635 concurrent allocations. When this limit is reached, deallocate resources to do additional allocations. Allocating files with the FREE operand helps to keep the allocations below the limit. This procedure also minimizes the time that critical data sets, volumes, and units are tied up. System output data sets also are spooled immediately when the files are closed, instead of when the NetView program ends.
  • If you specify the same operand more than once on the ALLOCATE command, the last one specified is used and the previous operands are ignored.
  • The NetView LISTA command displays the ddnames and dsnames of currently allocated files.
  • For disk files, the following operands are ignored by dynamic allocation:
    COPIES HOLD | NOHOLD
    DEN OUTLIM
    DEST POSITION
    FORMS WRITER
  • For tape files, the following operands are ignored by dynamic allocation:
    BLOCK | TRACK | CYLINDERS KEYLEN
    CONTIG | MXIG | ALX MSVGP
    COPIES OUTLIM
    DEST RELEASE
    DIR ROUND
    FORMS SPACE
    HOLD | NOHOLD WRITER
  • The QSAM stage uses one or more QSAM read or write operations. The NetView program uses the QSAM GET macro to perform read operations and the QSAM PUT macro to perform write operations. See the appropriate QSAM documentation for more information about the QSAM GET and the QSAM PUT.
    If the NetView program is running under z/OS® Version 1.10 or earlier, and if a QSAM read operation is performed on a newly allocated data set that is not managed by SMS before any write, the read operation might return residual data from the previously deleted data set. If this previously deleted data set had a different record size, the QSAM read operation fails with message 
    DWO970I QSAM : GET FAILED WITH RETURN CODE 1006
    Message DWO050E is also logged.
    To avoid these problems, you can perform one of the following steps:
    • Write a blank line to the data set before doing a read operation
    • Manage the data set with SMS
    • Start the NetView program under z/OS Version 1.11 or higher

Return Codes

The following return codes are returned by the QSAM stage, on the secondary output stream, as a signed, 10-digit decimal numbers:
Return Code
Meaning
0
QSAM completed successfully.
4
APPEND failed on a PDS member.
8
Error detected when attempting to access the data set. For example, a partitioned data set with no associated member name was requested.
12
The user is not authorized to the data set.
16
An open error occurred. Look for message IEC143I on your system console for more information.
20
An ABENDx13 occurred while trying to open the data set. See the system console for messages issued relating to this ABEND.
28
The data set is unavailable. It might be in use by another user or task.
32
The data set does not exist.
36
The NetView program does not support writing to this data set. For example, the data set might have been defined with RECFM(U).
40
A record with an incorrect length was encountered while reading the contents of the data set.
69
A syntax error was detected.
100
An internal failure or abend occurred.

Example: Reading from a Data Definition

The following reads data from a data set specified by a data definition: 
 PIPE QSAM (DD) allocddd
      | ...
where allocddd is the 'FILE' value from the ALLOCATE command.

Example: Reading from a Data Set Name

The following reads data from a data set specified by a data set name:

 PIPE QSAM (DSN) hiqual.midqual.lowqual(member)
      | ...
Note: If the DSN is not partitioned, omit '(member)'.

Example: When (DD) or (DSN) Is Not Specified

When neither (DD) or (DSN) is specified, QSAM examines the argument for periods or parentheses. The presence of these delimiters causes the argument to be considered a data set name. A single 1- to 8-character name is considered a data definition name. 
 MVS VARY 00A,ONLINE
 ALLOCATE FILE(RDR) UNIT(00A) OLD RECFM(F)LRECL(80) 
                    DSORG(PS) BLKSIZE(80)
 PIPE QSAM RDR
      | ...

Example: Writing to an Existing Data Definition

The following writes data from the input stream to a data set specified by a data definition: 
 PIPE ... |
      QSAM (DD) allocddd
      | ...
where allocddd is the 'FILE' value from the ALLOCATE command.

Example: Writing to an Existing Data Set Name

The following writes data from the input stream to a data set specified by a data set name:

 PIPE ... |
      QSAM (DSN) hiqual.midqual.lowqual(member)
      | ...
Note: If the DSN is not partitioned, omit (member).