dc_dam_status - Reference the status of a logical file

ANSI C, C++

#include <dcdam.h>
int  dc_dam_status (char *lfname, struct DC_DAMSTAT *stbuf,
                    int reserve, DCLONG flags)

K&R C

#include <dcdam.h>
int  dc_dam_status (lfname, stbuf, reserve, flags)
char      *fname;
struct  DC_DAMSTAT  *stbuf;
int        reserve;
DCLONG     flags;

The function dc_dam_status() returns the current logical file status to structure DC_DAMSTAT. The following values are returned:

Number of blocks in a logical file
Logical file block length
Physical file name corresponding to the logical file
Current logical file status (whether it is shut down)
Attribute of the logical file specified in the DAM service definition
Security attribute of the logical file specified in the DAM service definition

The function dc_dam_status() can be called before and after a logical file is opened with the function dc_dam_open().

When referencing the status of a logical file, specify the logical file name.

lfname

Specify a logical file name within eight bytes.

stbuf

Specify the address of a structure DC_DAMSTAT that receives the logical file status. The logical file status set in the function dc_dam_status() is returned in the structure.

phyfilno

Area used by the DAM service. Specify null character (0).

flags

Specify DCNOFLAGS.

stbuf

The logical file status data is returned in the format of structure DC_DAMSTAT as follows:

struct  DC_DAMSTAT {
                    int   st_block_len;
                    int   st_block_num;
                    char  st_file_ph_name[64];
                    char  st_file_stat;
                    char  st_file_def;
                    char  st_file_sec;
                    char  st_filler_1;
                    char  st_file_inf;
                    };

st_block_len
The block length of a logical file is returned.
st_block_num
The number of blocks in a logical file is returned.
st_file_ph_name
The physical file name corresponding to the logical file is returned.
st_file_stat
The current logical file status is returned as follows:
DCDAM_ST_NOT_HOLD: The logical file can be accessed.
DCDAM_ST_HOLD_LOG: The logical file is logically shut down.
DCDAM_ST_HOLD_OBS: The logical file is shut down with an error.
DCDAM_ST_HOLD_REQ: A shutdown request is being made for the logical file.
st_file_def
The attribute of the logical file specified in the DAM service definition is returned as follows:
DCDAM_ST_QUICK: DAM file ineligible for deferred update processing
DCDAM_ST_DEFERRED: DAM file eligible for deferred update processing
DCDAM_ST_NORECOVER: Unrecoverable DAM file
DCDAM_ST_CACHELESS: Unrecoverable DAM file specified by a cache-less access
st_file_sec
The security attribute of the logical file specified in the DAM service definition is returned as follows:
DCDAM_ST_NON: Security is not specified.
DCDAM_ST_SEC: Security is specified.
st_filler_1
Reserved area 1 (A null character (0) is set.)
st_file_inf
Reserved area 2 (The value -1 is set.)

Return value	Return value (numeric)	Explanation
DC_OK	0	The logical file status is set normally in the structure DC_DAMSTAT.
DCDAMER_PROTO	-1600	The function dc_rpc_open() is not called.
		N is specified for atomic_update in the user service definition. (This value is returned only when a recoverable DAM file is accessed.)
		The function dc_dam_start() is not called. (This value is returned only when an unrecoverable DAM file is accessed.)
DCDAMER_UNDEF	-1601	The logical file name specified for lfname is undefined.
DCDAMER_NOMEM	-1607	The memory became insufficient.
DCDAMER_PARAM_LFNAME	-1610	The logical file name specified for lfname is invalid.
DCDAMER_PARAM_FLAGS	-1611	The value specified for flags is invalid.
DCDAMER_PARAM_ERROR	-1612	The value specified for the argument is invalid.
		The value specified for stbuf is invalid.
		No null character is set for reserve.
DCDAMER_VERSION	-1618	The UAP is linked with a DAM library which is inoperable with the current DAM service.
DCDAMER_ACCESS	-1628	A DAM file whose status is to be referenced is protected with the security facility. The UAP that called the function dc_dam_status() has no access permission.
DCDAMER_NO_ACL	-1646	A DAM file whose status is to be referenced is protected with the security facility. There is no ACL for the corresponding file.

When the function dc_dam_status() is called, the DAM service does lock control to get data. So if the function dc_dam_status() is used too often, the throughput may be degraded because of the lock release wait time. Therefore, reference the DAM file status as little as possible while online.