CBL_CREATE_FILE

Usage

CAll "CBL_CREATE_FILE" 
     USING FILENAME, ACCESS-MODE, DENY-MODE, DEVICE, HANDLE
     RETURNING STATUS-CODE

Parameters

FILENAME (PIC X(n)) This is the name of a file to create. If this file does not exist, the open fails and sets return-code to 1. The filename parameter can be blank-terminated or terminated with low-values.
ACCESS-MODE (pic x comp-x)     This parameter is ignored (the file is always open for writing only), and the file is created anew. This means that if the file exists, it is truncated to 0 bytes, and if it does not exist, it is created.
DENY-MODE (pic x comp-x) Determines how other users can access the file: 0 to deny read and write access by other users, 1 to deny write access, 2 to deny read access, and 3 to allow all other users. This flag has an effect only on Windows systems.
DEVICE (pic x comp-x) This is not used and must be 0.
HANDLE (pic x(4) comp-x) This is set to the handle of the file created. Use this handle in the other functions.

Description

This routine is used for creating files and returns 0 on success and non-zero if an error occurred. The error is a special encoding of the digit 9 with the ANSI-74 error code, or the runtime system error number if no ANSI-74 error code pertains to the error. If RETURN-CODE is non-zero after calling this routine, you must process it as a file status, for example:

01  file-status-group.
    03  file-status     pic xx comp-x. 
    03  redefines file-status. 
        05  fs-byte-1  pic x. 
        05  fs-byte-2  pic x comp-x.
. . . 
call "CBL_CREATE_FILE" using parameters 
if return-code not = 0 
    move return-code to file-status 
. . .

At this point fs-byte-1 contains 9 and fs-byte-2 contains the ANSI-74 error code, or a runtime system error number.

Note: This routine is written in C and is called via the "direct" method, so it is not possible for the runtime to validate parameters for accuracy. Passing unexpected parameters will result in undefined behavior and possibly even a MAV.