The general, function‑independent structure identifies a requested function and provides the specifications required by all Access Module function calls. For detailed examples, refer to the pmdcomt.h and pmddamt.h header files in Chapter 4: “Header File Examples.”
typedef struct _pmiCmdBlock
{
char EyeCatcher[pmiMAX_EC_LEN];/* Struct eyecatcher string */
pmUInt32 StructLength; /* Length of this structure */
pmUInt32 Reqtype; /* function request indicator */
pmReturnType Retcode; /* identical to function return value */
pmTrceLvl_t TraceLvl; /* Requested diagnostic trace level */
/* Descriptive error text */
pmNameBuf_t ErrMsg; /* when Retcode is pmrcFailure */
} pmiCmdBlock_t;
where:
Parameter |
Field |
Description |
EyeCatcher |
input |
Structure description string, such as pmCmdBlock. |
StructLength |
input |
Total structure length, including the EyeCatcher string. |
Reqtype |
input |
Specific function request, as listed in Table 4. |
Retcode |
output |
Value assigned by the Access Module function as one of those defined in the pmdcomt.h. header file. Although additional function‑specific return codes are defined with each function, typical interface return codes are listed in Table 5. |
TraceLvl |
input |
Default trace level to be associated with all functions related to this operation. |
ErrMsg |
output |
Two‑field value assigned by the Access Module function when Retcode is set to pmrcFailure. These fields provide the following: Whenever an error condition is detected, the Access Module must map the error to one of the error codes defined in the pmdcomt.h header file. If a well‑defined match is not found, the Access Module must return a value of pmrcFailure and provide an error description string in this ErrMsg field. The client utility then presents the error message to the user. |
The following table lists the function requests for Reqtype.
Reqtype |
Description |
pmiPIDMOptInit |
Access Module initialization |
pmiPIDMOptOpen |
File open |
pmiPIDMOptClose |
File close |
pmiPIDMOptCloseR |
File close and release media |
pmiPIDMOptRead |
File read |
pmiPIDMOptWrite |
File write |
pmiPIDMOptGetPos |
Get position of currently open file |
pmiPIDMOptSetPos |
Set position of currently open file |
pmiPIDMOptShut |
Access Module shutdown (cleanup) |
pmiPIDMOptID |
Access Module identification |
pmiPIDMOptGetA_A |
Get (obtain) an Access Module attribute |
pmiPIDMOptGetF_A |
Get (obtain) a file attribute |
pmiPIDMOptPutA_A |
Put (provide) an Access Module attribute |
pmiPIDMOptPutF_A |
Put (provide) a file attribute |
The following table lists typical interface return codes.
Return Code |
Description |
pmrcOK |
No error conditions encountered. |
pmrcUnsupported |
The function requested by Reqtype is not supported. |
pmrcBadTraceLvl |
The value of TraceLvl is out of range. |
pmrcBadParm |
One or more of the supplied parameters is invalid. |
pmrcAPInotReady |
The Access Module has not been initialized. |
pmrcAllocErr |
A memory allocation error occurred. |
pmrcFailure |
General failure return code. See the description of the ErrMsg parameter. |
See Chapter 3: “Access Module Functions” for more information about Access Module functions.