PMDF Programmer's Reference Manual
PMDF-PRM-6.0

Retrieve an entry from the queue cache database.

VMS FORMAT

status = PMDF_queue_cache_get_entry

(cache_context, item_list, reserved1, reserved2)

C FORMAT

status = PMDFqueueCacheGetEntry

(cache_context, item_list, reserved1, reserved2)

void PMDFqueueCacheGetEntry (cache_context, item_list, 
                             reserved1, reserved11, 
                             reserved2, reserved22) 
         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 PMDF_queue_cache_get_entry.

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

PMDF_queue_cache_get_entry 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 PMDF_queue_cache_get_entry 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 PMDF_queue_cache_end. 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 and NT.

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. On NT systems, it is a FILETIME.
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. On NT systems it is a FILETIME. item_address should point to a buffer where the value is to be written.
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. On NT systems it is a FILETIME. item_address should point to a buffer where the value is to be written.
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. On NT systems it is a FILETIME. item_address should point to the buffer where the value is to be written.
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.