PUNCH

Options

Notes:

¹ You can enter Options in any order between the parentheses.

Authorization

General User

Purpose

Use the PUNCH command to punch a CMS file to your virtual punch.

Operands

fn: is the file name of the file to be punched. This field must be specified.
ft: is the file type of the file to be punched. This field must be specified.
fm: is the file mode of the file to be punched. If you specify it as an asterisk (*), the standard order of search is followed and the first file found with the specified file name and file type is punched. If fm is not specified, your disk or directory accessed as A and its extensions are searched.

Options

Header: inserts a control card in front of the punched output. This is the default. This control card indicates the file name and file type for a subsequent READCARD command to restore the file to a disk or directory. The control card format is shown in Table 1.
NOHeader: does not punch a header control card.
MEMber *
MEMber membername: punches members of MACLIBs or TXTLIBs. If an asterisk (*) is entered, all individual members of that macro or text library are punched. If membername is specified, only that member is punched. If the file type is MACLIB and the MEMBER membername option is specified, the header contains MEMBER as the file type. If the file type is TXTLIB and the MEMBER membername option is specified, the header card contains TEXT as the file type.

Table 1. Header Card Format
Column	Number of Characters	Contents	Meaning
1	1	:	Identifies card as a control card.
2-5	4	READ	Identifies card as a READ control card.
6-7	2	blank
8-15	8	fname	File name of the file punched.
16	1	blank
17-24	8	ftype	File type of the file punched.
25	1	blank
26-27	2	fmode	File mode of the file punched.
28	1	blank
29-34	6	volid	Label of the disk from which the file was read or a — if read from a directory.
35	1	blank
36-43	8	mm/dd/yy	The date the file was last written.
44-45	2	blank
46-50	5	hh:mm	The time of day the file was written.
51-80	30	blank

Usage Notes

You can punch fixed- or variable-length records with the PUNCH command, as long as no record exceeds 80 characters. Records with less than 80 characters are right-padded with blanks. Records longer than 80 characters are rejected. PUNCH changes variable-length record files to fixed-length 80-byte record files.
If you punch a MACLIB or TXTLIB file specifying the MEMBER * option, a READ control card is placed in front of each library member. If you punch a library without specifying the MEMBER * option, only one READ control card is placed at the front of the deck.
One spool punch file is produced for each PUNCH command; for example:
```
punch compute assemble (noh
```
punches the file COMPUTE ASSEMBLE, without inserting a header card. To transmit multiple CMS files as a single punch file, use the CP SPOOL command to spool the punch with the CONT option.
Note: If multiple files are sent with continuous spooling (using CP SPOOL PUNCH CONT) and a series of DISK DUMP commands, RECEIVE recognizes only the first file identifier (file name and file type). Any files having the same file identifier as existing files on your disk or directory accessed as A will overlay those files.

As a sender, you can avoid imposing this problem on file recipients by doing any of the following:
1. Always use SENDFILE, which resets any continuous spooling options in effect.
2. Do not spool the punch continuous.
3. If you must send files with continuous spooling, warn the recipient(s) files are being sent in this manner and list the file identifiers of the files you are sending.
Similarly, if the punch is spooled continuous and PUNCH is used to send multiple files, the file is read in as one file with :READ cards imbedded. In this case, although no files are overlaid, the recipient must divide the file into individual files. This problem can also be avoided by using SENDFILE or by not spooling the punch continuous.
If the MEMBER option is specified more than once, only the last member specified will be punched. However, if one MEMBER option is coded with an asterisk (*), and another MEMBER option is specified with membername, only the member specified by membername will be punched, regardless of their order on the command line.
For example, if you code:
```
punch one maclib (member example1 member example2
```
only EXAMPLE2 will be punched. If you code:
```
punch one maclib (member example1 member *
```
only EXAMPLE1 will be punched.
When punching members from CMS MACLIBs, each member is followed by a // record, which is a MACLIB delimiter. You can edit the file to delete the // record.

Responses

None.

The CMS ready message indicates the command completed without error (the file was successfully spooled); the file is now under control of CP spooling functions. You may receive a message from CP indicating the file is being spooled to a particular user's virtual reader.

When you PUNCH empty files, file attribute data is sent. You must use the HEADER option, or you will get this message:

Error punching file fileid; NOHEADER option invalid
for empty files

Messages and Return Codes

DMS002E File [fn [ft [fm]]] not found [RC=28]
DMS008E Device vdev {invalid or nonexistent|is an unsupported device type} [RC=36]
DMS013E Member membername not found [RC=32]
DMS026E Invalid parameter parameter in the option field fieldname [RC=24]
DMS033E File fn ft fm is not a library [RC=32]
DMS039E No entries in library fn ft fm [RC=32]
DMS044E Record exceeds allowable maximum [RC=32]
DMS069E Filemode mode not accessed [RC=36]
DMS104S Error nn reading file fn ft fm from disk or directory [RC=100]
DMS118E Error punching file fileid; NOHEADER option invalid for empty files [RC=24]
DMS123S Error nn punching file fn ft fm [RC=100]

Additional system messages may be issued by this command. The reasons for these messages and their location are:

Reason	Location
Errors in command syntax	Command Syntax Error Messages