Extract_Shutdown_Time - Query the shutdown time of the server

By issuing the Extract_Shutdown_Time (CMESHT) call, a program can obtain the current shutdown time of the UTM partner application.

The shutdown time is returned in printable format of length received_length and has the Universal Time Coordinated (UTC) time format. It still has to be converted to the time in the local time zone.

The Extract_Shutdown_Time call is permitted in the "Send" and "Receive" states as well as in the "Reset" state immediately after a Receive-/Receive_Mapped_Data call or after an Extract_Shutdown_State call .

This function is not part of the CPI-C specification but an additional function of the UPIC carrier system.

Syntax

CMESHT (conversation_ID, buffer, requested_length, data_received, received_length, return_code)

Parameters

--> conversation_ID	Identification of the conversation
<-- buffer	Buffer in which the data is received. If the return value of data_received is CM_NO_DATA_RECEIVED or the return value of received_length = 0, the content of buffer is undefined. buffer returns the time at which the application is shut down. The individual bytes have the following meanings: Bytes 1 - 8: Date in the format yyyymmdd: yyyy:Year, four-digit mm: Month dd: Day Bytes 9 - 11 ddd: Day in year Bytes 12 - 17: Time in the format hhmmss (UTC format): hh: Hour mm: Minute ss: Second
--> requested_length	Maximum length of the data that can be received.
<-- data_received	Specifies whether the program has received all the data. If the result (return_code) does not have one of the values CM_OK or CM_DEALLOCATED_NORMAL then the value of data_received is undefined. The data_received variable can have the following values: CM_COMPLETE_DATA_RECEIVED The data was received in full. CM_INCOMPLETE_DATA_RECEIVED The data was not received in full. CM_NO_DATA_RECEIVED No data was received.
<-- received_length	Length of the received data. The value of received_length is undefined if return_code is not equal to CM_OK.
<-- return_code	Result of the function call

Result ( return_code )

CM_OK

Call OK

CM_PROGRAM_PARAMETER_CHECK

The value in conversation_ID is invalid.
The value of conversation_ID is invalid because the function was called more than once after the end of the conversation or because no conversation existed at the time (there was no Initialize_Conversation call after the Enable_UTM_UPIC call). Alternatively, the value for requested_length is greater than 32767 or smaller than 1.

CM_PRODUCT_SPECIFIC_ERROR

The UPIC instance could not be found.

Note

• This function has not been implemented at its full level of complexity in accordance with the CPI-C specification. The simplifications compared to CPI-C are as follows:

The internal buffer possesses a restricted size of 1024 bytes.

If the value of requested_length is smaller than the length of the internally stored extended information then the buffer made available by the application program is completely filled and data_received is set to CM_INCOMPLETE_DATA_RECEIVED. It is not possible to obtain the remaining data using further CMESHT calls.

• After the end of the conversation, the value of conversation_ID remains valid for this function call until Initialize_Conversation or Extract_Shutdown_Time is called.

Behavior in the event of errors

CM_PROGRAM_PARAMETER_CHECK

Modify program.

CM_PRODUCT_SPECIFIC_ERROR

The operating system cannot provide sufficient memory for internal buffers. Check whether the memory requirement of your program is too high and if necessary reboot your system.

Function declaration: Extract_Shutdown_Time

CM_ENTRY Extract_Shutdown_Time( 
              unsigned char            CM_PTR  conversation_ID, 
              unsigned char            CM_PTR  buffer, 
              CM_INT32                 CM_PTR  requested_length, 
              CM_DATA_RECEIVED_TYPE    CM_PTR  data_received, 
              CM_INT32                 CM_PTR  received_length, 
              CM_RETURN_CODE           CM_PTR  return_code )