Chapter Contents

Previous

Next

JES Spool File I/O

A SAS/C program can retrieve files from the JES spool, write a file directly to the JES spool, and send a file to a remote destination via systems connected to a JES/RSCS network. This feature makes it easy for you to generate and review output because you don't have to locate and then browse the sequential data set where extrapartition transient data output is usually sent.

Spool files consist of variable-length records up to 32K-8 bytes long. They do not have record format, record length, and block size characteristics. Spool files may have a JES class designation, and they may contain carriage-control characters. Spool file I/O is strictly sequential access. Like transient data files, essentially no positioning is available (output files are always positioned to EOF; input files are always positioned to the start of the file).

Input from JES is single-threaded; that is, only one transaction at a time in a CICS region may use the CICS input interface. However, many transactions can concurrently create output spool files. Input spool files are closed with a disposition of DELETE, unless an error occurs during processing, in which case the file is closed with a disposition of KEEP. If an input file is closed with the disposition of KEEP, the file remains on the spool and can be retrieved on a subsequent input operation.

Any open spool files are automatically closed by the EXEC CICS SYNCPOINT command. To avoid problems, issue the fclose function for any open spool file before issuing this command. Consult the IBM documentation on the CICS interface to JES for more details.

JES Spool Filename Specification

A spool filename is of the form userid.node<.class>, where userid and node are one to eight alphanumeric or national ($, #, or @) characters. An asterisk (*) may be specified for userid and node to direct an output file to the local spool. class is an optional alphanumeric character; the default is class A. For input spool files, userid is an external writer name that must begin with the same first four characters as the VTAM APPLID of the CICS system. See the IBM JCL reference manual for more information about specifying external writer names, userids, and node names. The following are examples of how to specify spool filenames:

• Redirect stdout to a userid at another node:

  char *_stdonm = "spl:sascuser.vm";
  printf("hello from CICS");

• Read a record from a spool file:

  FILE *fptr;
  
  fptr = fopen("spl:cicstest.*", "rb");
  len  = afread(record, 1, 255, fptr);

• Submit a job for execution at the node named OS/390 :

  fptr = afopen("spl:intrdr.OS/390.a", "w", 
         "seq", "recfm=f,reclen=80");
  
  fprintf
  (fptr, "%s\n", "//BR14 JOB (acct),pgmr_name");
  fprintf
  (fptr, "%s\n", "// EXEC PGM=IEFBR14");
  fprintf(fptr, "%s\n", "/*EOF");

Specifying Amparms for JES Spool Files

The file characteristics amparms provide advice to the library about what file characteristics to expect. JES spool files may have either fixed- or varying-length records; however, files on the spool are actually formatted as variable-length records. The library will process a spool file according to the specifications of the file characteristics amparms.

Note:    The defaults of recfm=v / reclen=255 allow a program to read and write equal-length records just as easily as variable-length records.  

recfm

Consider the following points when using this amparm:

• If recfm=f is specified, the program expects records of equal length.

• If recfm=v is specified, the program expects records of variable length.

• recfm=u is treated as recfm=v .

reclen

Consider the following points when using this amparm:

• The value of this amparm tells the library the maximum input or output record length to expect; this value is used internally by the library as a buffer size. Record length cannot exceed the CICS maximum of 32,760.

• For ESA versions of CICS, reclen=x is supported, which means that records can be of any length up to the CICS maximum.

• You cannot specify both reclen=x and recfm=f .

blksize

Block size can be specified, but it is ignored for JES spool files.

Default Values

Default values for JES spool file characteristics amparms are

recfm	v
reclen	255
blksize	not applicable

Support for CICS File Control

Traditional CICS commands for random access (such as READ, WRITE, and DELETE) and commands for sequential access (such as STARTBR and READNEXT) are supported. The only area for special consideration is the record identification (RID) field for certain commands.

RID Field in ISSUE Commands

In the ISSUE REPLACE, ISSUE ADD, ISSUE ERASE, and ISSUE NOTE commands, if the record identification field is a relative record number, the RIDFLD option is expected to be an unsigned int type. Otherwise, the option is expected to be a pointer type (presumably a pointer to a key).

For the READ, WRITE, DELETE, STARTBR, READNEXT, READPREV, and RESETBR commands, the RIDFLD option is generally expected to be a pointer type, that is, a pointer to a key.

Each command has a set of options that, if used, specifies whether the argument will be either a relative byte address or a relative record number and, therefore, will be an unsigned int type. Here's the list of options for each command:

Command	Options
READ	RBA, RRN, GENERIC, GTEQ
READNEXT	RBA, RRN
READPREV	RBA, RRN
RESETBR	RBA, RRN
STARTBR	RBA, RRN
WRITE	RBA, RRN, MASSINSERT

Note:    When the MASSINSERT option of the WRITE command is used, the RIDFLD option is expected to be of type void * , rather than of the unsigned int type.  

Chapter Contents

Previous

Next

Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.