PMDF Programmer's Reference Manual
Previous Contents Index

PMDFqueueCacheGetEntry

Retrieve an entry from the queue cache database.

PASCAL

status = PMDF_queue_cache_get_entry

(cache_context, item_list, reserved1, reserved2)

argument information

Argument Data type Access Mechanism
cache_context context pointer read/write reference
item_list item list read/write reference
reserved1 descriptor read reference
reserved2 descriptor read reference

C

status = PMDFqueueCacheGetEntry

(cache_context, item_list, reserved1, reserved2)

argument information


void PMDFqueueCacheGetEntry 
           (PMDF_qc                 **cache_context, 
            PMDF_keyword_item_list  *item_list, 
            void                    *reserved1, 
            int                      reserved11, 
            void                    *reserved2, 
            int                     *reserved22)

Arguments

cache_context

Queue cache read context created with PMDFqueueCacheGetEntry .

item_list

Item list specifying actions to be taken. item_list is the address of a list of item descriptors, each of which specifies an action and provides the information needed to perform that action. See the description below for further details.

reserved1, reserved11, reserved2, reserved22

These arguments are presently ignored. Pass values of zero.

Description

PMDFqueueCacheGetEntry is used to dump the contents of the queue cache database. On the first call to the routine, the cache_context argument should be set to zero. It will then be created by PMDFqueueCacheGetEntry and returned along with the first queue cache entry. Repeated calls should then be made using this cache context to obtain the remaining queue cache entries. When there are no more entries to return, the context will be disposed of and PMDF__EOM returned. To prematurely abort the listing, call PMDFqueueCacheEnd . A list of item descriptors --- an item list --- is used to specify, for each queue cache entry, what values to return. The item_list argument is the address of the first item descriptor in the list. Each item descriptor specifies an action and provides the information needed to perform that action. The list of item descriptors is terminated with an item descriptor with an item_code field value of PMDF_QC_END_LIST . Each item descriptor has the following C-style structure declaration: 


typedef struct { 
  int   item_code; 
  int   item_blength; 
  void *item_address; 
  int   item_length; 
  int   item_status; 
} PMDF_keyword_item_list;
where
Field name Description
item_code Item code chosen from Table 1-7 indicating the value to return. The PMDF_QC_END_LIST item code indicates the end of the item list. Used for input only.
item_blength Maximum length in bytes of the buffer pointed at by item_address. For string buffers, this length does not include any null terminator. Used for input only.
item_address Pointer to the buffer where the indicated value is to be written. Used for input only.
item_length On output, this field is set to the length in bytes of the value written to the buffer pointed at by item_address. This length does not include any null terminator use to terminate string values. Used for output only.
item_status Status code associated with writing the value to the buffer. Will be PMDF__OK for a success. In the case of an error, will generally be PMDF__STRTRU indicating that the value was truncated to fit. Used for output only.
The allowed item code values are given in Table 1-7. A sample program, api_example11.pas and api_example12.c , are provided in the directory of example programs, (PMDF_ROOT:[DOC.EXAMPLES] on OpenVMS and /pmdf/doc/examples/ on UNIX.

Table 1-7 PMDF_queue_cache_get_entry Item Codes
Item code Description
PMDF_QC_END_LIST Denotes the end of the item list. The item_address, item_blength, and item_length fields are ignored.
PMDF_QC_CHAIN This item entry points to another item list to process. item_address is a pointer to another item list to process. The item_blength and item_length fields are ignored.
PMDF_QC_CHANNEL Name of the channel to which this message is queued. item_address is a pointer to a buffer of length at least CHANLENGTH+1 bytes. The channel name is written to this buffer and null terminated.
PMDF_QC_CREATION_DATE_BIN Binary representation of the message file's creation date and time. On OpenVMS systems, this is a quadword binary time. On UNIX systems it is a time_t value.
PMDF_QC_CREATION_DATE_STR ASCII string representation of the message file's creation date and time. item_address should point to a buffer of length at least ALFA_SIZE+1 bytes. The date and time will be written to that buffer and null terminated.
PMDF_QC_DEFERRED_DATE_BIN Binary representation of any "Deferred-delivery-date:" specified in the message's RFC 822 header. Usually this value will be zero since PMDF by default ignores that header line. PMDF must be explicitly configured to honor it via the deferred channel keyword. On OpenVMS systems, this binary time value is a quadword binary time. On UNIX systems it is a time_t value.
PMDF_QC_DEFERRED_DATE_STR ASCII string representation of any "Deferred-delivery-date:" specified in the messages RFC 822 header. item_address should point to a buffer of length at least ALFA_SIZE+1 bytes. The date and time will be written to that buffer and null terminated.
PMDF_QC_EXPIRY_DATE_BIN Binary representation of any "Expiry-date:" specified in the message's RFC 822 header. On OpenVMS systems, this binary time value is a quadword binary time. On UNIX systems it is a time_t value.
PMDF_QC_EXPIRY_DATE_STR ASCII string representation of any "Expiry-date:" specified in the messages RFC 822 header. item_address should point to a buffer of length at least ALFA_SIZE+1 bytes. The date and time will be written to that buffer and null terminated.
PMDF_QC_FILENAME Full path to the message file. item_address should point to a buffer of length at least ALFA_SIZE+1 bytes. The file path will be written to that buffer and null terminated.
PMDF_QC_LAST_TRY_DATE_BIN Binary representation of the date and time at which delivery was last attempted for this message. A value of zero indicates that delivery has not yet been attempted. On OpenVMS systems, this binary time value is a quadword binary time. On UNIX systems it is a time_t value.
PMDF_QC_LAST_TRY_DATE_STR ASCII string representation of the date and time at which delivery was last attempted for this message. When the message has yet to be attempted, the system's zero time representation is returned. item_address should point to a buffer of length at least ALFA_SIZE+1 bytes. The date and time will be written to that buffer and null terminated.
PMDF_QC_OWNER_USERNAME Username associated with the process which enqueued this message to PMDF. item_address should point to a buffer of length at least ALFA_SIZE+1 bytes. The username will be written to that buffer and null terminated.
PMDF_QC_PRIORITY Processing priority assigned to the message. This is a four byte, signed integer value. Possible values are PMDF_CKEY_V_THIRD_CLASS, PMDF_CKEY_V_SECOND_CLASS, PMDF_CKEY_V_NON_URGENT, PMDF_CKEY_V_NORMAL, PMDF_CKEY_V_URGENT. item_address should point to the location where the value is to be written.
PMDF_QC_RECIPIENT_COUNT Count of envelope "To:" addresses associated with the message. This is a four byte, signed integer value. item_address should point to the location where the value is to be written.
PMDF_QC_RECIPIENT_SYSTEM String representation of the destination system's host name. item_address should point to a buffer of length at least ALFA_SIZE+1 bytes. The host name will be written to that buffer and null terminated.

Return Values

PMDF__OK Normal, successful completion; queue cache entry returned.
PMDF__EOF Normal, successful completion; no more queue cache entries to return.
PMDF__NO Cannot access queue cache database. No queue cache entry returned.

Previous Next Contents Index