_open

Open a file.

int _open (char * filename, int open_flags[, int permission_flags[, char * dcb]]);

int open (char * filename, int open_flags[, int permission_flags[, char * dcb]]);

Required Header
<io.h>

Return Value

Each of these functions returns a new handle to the open file. -1 indicates an error.

Parameters

filename

  The filename of the file to open

open_flags

  The flags used to determine which mode to open the file in

permission_flags

  Included for backwards compatability, not otherwise used

dcb

  A string specifing dcb defaults, used if the system cannot determine them

Remarks

The _open function opens the file specified by filename in the mode determined by the open_flags which specify read, write, append, binary or text. The allowable open flags are:

O_APPEND or _O_APPEND  Appends to the end of the file
O_BINARY or _O_BINARY  Opens the file in non-translated mode
O_CREAT  or _O_CREAT   Creates the file if one does not already exist
O_EXCL   or _O_EXCL    Prevent existing files from being overwritten
O_RDONLY or _O_RDONLY  Opens the file in read only mode
O_RDWR   or _O_RDWR    Opens the file in read/write mode
O_TEXT   or _O_TEXT    Opens the file in text-translated mode (Ignored for HFS files)
O_TRUNC  or _O_TRUNC   The default file write only mode, erases its content first
O_WRONLY or _O_WRONLY  Opens the file in write only mode
O_BINARY or O_TEXT can be used to open _O_RDWR read/write files, but where VB files with a lrecl less than blksize-4 are not supported with errno set to EACCES. There are no record delimiters used in read/write mode and every block written will be full (including the last block) which prevents easy file-size control. The last block is padded with nulls or spaces (bin/txt) when the file is closed. A PDS member can be updated, but not extended after it is first closed and _O_APPEND cannot be used at all with a member.

Text translation mode otherwise only effects the operation of Fixed-record file processing, by padding incomplete records (delimited by a newline character) with spaces when writing, and appending a newline to the 'trimmed' record when reading. When binary-mode fixed-records are written, an incomplete record (delimited by closing the file) is padded with binary zeros. In Variable-record processing, a newline is added to the end of every record read regardless of the mode the file was open with. A newline always specifies the end of a record being written. The actual file content never contains a newline character. Undefined-record processing returns a special two-byte short integer at the begining of each record to specify the record length, likewise the same two bytes should be passed to the write routine to specify the length of a new record.

extern int _vmode; may be defined and set to value 1 to enable V[B] file types to use and return the same half-word length in the data stream (like Undefined-record processing) to allow newlines and other binary information to be physically read and written. Only Binary non-translated mode opened files check _vmode. File positioning using seek is effected by the _vmode setting. A value of 2 will prevent newlines from being added or used as record boundaries.

extern int _umode; may be defined and set to a zero value so U file types do not require or return a length indicator for records. Each record written will be the maximum blocksize, except the last which can be smaller.

See file modes for more detailed information.

When using a dcb string it is neccessary to also have a dummy permission_flags value and also include the special open_flags value _O_ATTRS. The dcb string can be made up from the following optional components:

"recfm=u|f[b]|v[b],blksize=x,lrecl=y,klen=z"
Where x, y and z are the required DCB values. HFS files never use the extra attributes.

To force these values into the DCB before the open service is issued, use an extra string component: ",force"

A VTOC can be opened by specifying ",vtoc" where the disk accessed is that where the DD or DSN is located. If no filename is specified, ie. an empty string, extra components "volser=..." and "unit=..." need to be added to locate the desired disk. Only the 96 non-key bytes from each vtoc entry are read by JCC. The open mode must be set to read binary for the function to succeed.

The dcb string can also specify ",vmode=0|1|2" and/or ",umode=0|1" to localise the effect on file-processing.

The filename may be preceeded by a style ("//DDN:", "//DSN:" or "//HFS:") to specify which library routines should be used to access the file. A filename starting with a single "/" is assumed to be HFS.

_style, described in the JCC Library, determines the default file style for opening files. This is a character pointer which by default points to "//DDN:" and which may be altered to point to a user defined string specifying "//DSN:" or "//HFS:" if that default style is desired. extern char * _style; needs to be defined before doing this.

When O_CREAT is specified for a PS (memberless) DSN style dataset, the following dcb values may also be used:

"volser=vvvvvv,unit=uuuuuu,pri=mmm,sec=nnn,rlse"
Which specify the placement and size of a newly created PS dataset. These values are only used when the dataset doesn't already exist, volser, sec and rlse are optional - both recfm and blksize must be specified to create a new dataset. Space is allocated in track (TRK) units.

New open processing allows uncatalogued files to be opened by using both volser= and unit= values and the new ",notcat" value. The file will not be found/opened if it does not exist on the volume specified, even if it is catalogued. There is also a new value ",dontcat" which prevents newly created datasets from being catalogued.

A PDS can be created by additionally specifying the value ",dirblks=" with your desired value. Although write binary must be issued for the creation to take place, the actual resulting file is finally opened in read binary ready to allow listing the empty PDS directory. You cannot open a PDS in write mode without a member name.

DSN filenames starting with "&&" are created when opened for the first time, and deleted when the JCC compiled program ends. 1000 temporary files may be created in this way per JCC program, although only 256 files may be open at the same time. Once a "//DSN:&&DSNAME" temporary file has been created, it may be opened and closed as many times as needed by the running program. Unlike JCL, use the same filename to (re)access the same temporary file.

To use a temporary file with another program in the same address-space, you may obtain the internal DD name used for the temp file with the int __get_tmpddn (char * tmpnam, char * ddn9) function. tmpnam would be "&&DSNAME" and ddn9 would be your char array (of length 9) to accept the resulting unpadded null-terminated ddname string. The function returns 1 when a name was copied into your buffer, and 0 on failure to locate the file.

The DD, DSN, Member and Volume-Serial names of any open JCC dataset can be obtained by using the special function:

int __get_ddndsnmemb (int handle, char * ddn, char * dsn,
                     char * member, char * serial, unsigned char * flags);
Where member will be set to an empty string if the file is sequential. If the device is a terminal, serial will also be set to an empty string and dsn will be set to "TERMFILE". You may pass NULL for any of the (u)char * parameters if you are not interested in that particular value. Space must exist in your buffers for returning the longest possible results for each value, plus a null terminator. That's 9, 45, 9 and 7 bytes for the first 4 parameters respectively. The flags returned need an 11 byte area and include the following information from the JFCB:

TSDM : Offset 0, 1 byte.
IND1/2 : Offset 1, 2 bytes.
KEYLEN : Offset 3, 1 byte.
DSORG : Offset 4, 2 bytes.
RECFM : Offset 6, 1 byte.
BLKSIZE: Offset 7, 2 bytes.
LRECL: Offset 9, 2 bytes.

A return value of -1 indicates an error prevented any values from being returned, 0 indicates successful execution. HFS files are not supported. Hint: Use the fileno function to obtain a handle from a stream to use with this function.

Memory files are now supported by the JCC library. Use a style or prefix of //MEM: to create a new or access an existing memory file. Note that only the current JCC program will have access to a memory file, you cannot access a memory file created within one JCC program from another JCC program even if the second JCC program was executed by the first. You cannot remove, unlink or rename a memory file once it is created. You can however release all memory used by a memory file by reopening it with the O_TRUNC parameter flag. Only standard heap memory can be used for memory files in JCC. Text mode has no meaning for memory files in the JCC library and access is always read/write regardless of what is specified in the open flags.

Low Level I/O

See Also    _close, _dup, _dup2, fopen, __getdcb, remove, _unlink