14.1 List of simulation functions and processing

This section lists the offline tester simulation functions and provides notes on function simulations.

Organization of this section
(1) Simulation functions
(2) Notes on simulation functions

(1) Simulation functions

Table 14-1 lists the offline tester simulation functions for simulating OpenTP1 functions.

Table 14-1 List of offline tester simulation functions

TypeFunction name [prog_name (request_code)] <DML>PurposeTracesReturn valueFunction processing
Control of system operation (adm)dc_adm_call_command
[CBLDCADM(COMMAND)]
Executes an operating command.YYReturns data from the operating command result data file.
dc_adm_complete
[CBLDCADM(COMPLETE)]
Notifies completion of user server startup.YY--
dc_adm_status
[CBLDCADM(STATUS)]
Notifies user server status.YYReturns DCADM_STAT_START_NORMAL (return value) or zero (return code) at normal termination.
dc_adm_get_nd_status_beginStarts status acquisition at the OpenTP1 node.YYGets the number of node IDs set in the function return values file.
dc_adm_get_nd_status_nextGets OpenTP1 node status.YYGets the node ID set in the function return values file. Returns DCADM_STATUS_NORMAL (C return value) at normal termination.
dc_adm_get_nd_status_doneEnds status acquisition at the OpenTP1 node.YY--
dc_adm_get_nd_statusGets OpenTP1 node status.YYReturns DCADM_STATUS_NORMAL (return value) at normal termination.
dc_adm_get_node_idGets the local node ID from the system common definition.YYGets the node ID set in the function return values file.
dc_adm_get_sv_status_beginStarts server status acquisition.YYGets the number of server names set in the function return values file.
dc_adm_get_sv_status_nextGets server status at the OpenTP1 node.YYGets the server name set in the function return values file. Returns DCADM_STATUS_NORMAL (C return value) at normal termination.
dc_adm_get_sv_status_doneEnds server status acquisition.YY--
dc_adm_get_sv_statusGets status of a specified server.YYReturns DCADM_STATUS_NORMAL (return value) at normal termination.
dc_adm_get_nodeconf_beginStarts node ID acquisition.YYReturns the number of node IDs set in function return values file.
dc_adm_get_nodeconf_nextGets multi-node area ID for the UAP that issued the function, or all node IDs of specified subareas.YYReturns the node IDs set in the function return values file.
dc_adm_get_nodeconf_doneEnds node ID acquisition.YY--
DAM file service (dam)dc_dam_close
[CBLDCDAM(CLOS)]
Closes a DAM file.YYCloses a DAM file.
dc_dam_create
[CBLDCDMB(CRAT)]
Allocates a physical file.NNCreates a DAM file and returns the file descriptor.
dc_dam_end
[CBLDCDAM(END)]
Declares to stop using files not subject to recovery.YY--
dc_dam_get
[CBLDCDMB(GET)]
Reads a physical file block.NNReads a specified block from a DAM file to a specified buffer.
dc_dam_hold
[CBLDCDAM(HOLD)]
Logical shutdown of a DAM fileYYSets shutdown status in the DAM file header and shuts down the DAM file.
dc_dam_iclose
[CBLDCDMB(CLOS)]
Closes a physical file.NNCloses a DAM file.
dc_dam_iopen
[CBLDCDMB(OPEN)]
Opens a physical file.NNOpens a DAM file and returns the file descriptor.
dc_dam_open
[CBLDCDAM(OPEN)]
Opens a DAM file.YYOpens a DAM file and returns the file descriptor. Locks the file if lock is specified for the file.
dc_dam_put
[CBLDCDMB(PUT)]
Writes a physical file block.NNWrites buffer contents to a specified DAM file block.
dc_dam_read
[CBLDCDAM(READ)]
Reads a DAM file block.YYReads a specified DAM file block to a specified buffer. Locks the file if lock is specified for the block.
dc_dam_start
[CBLDCDAM(STRT)]
Declares to start using files not subject to recovery.YY--
dc_dam_status
[CBLDCDAM(STAT)]
Shows DAM file state.YYReturns the DAM file state.
dc_dam_release
[CBLDCDAM(RLSE)]
Releases DAM file shutdown status.YYResets the shutdown status in the DAM file header and cancels the shutdown of the DAM file.
dc_dam_rewrite
[CBLDCDAM(REWT)]
Updates a DAM file block.YYWrites the contents of a specified buffer to a specified DAM file block.
dc_dam_write
[CBLDCDAM(WRIT)]
Outputs a DAM file.YYWrites the contents of a specified buffer to a specified DAM file block.
Shared table service (ist)dc_ist_close
[CBLDCIST(CLOS)]
Closes IST table.YYCloses the IST table.
dc_ist_open
[CBLDCIST(OPEN)]
Opens IST table.YYOpens the IST table and returns its descriptor.
dc_ist_read
[CBLDCIST(READ)]
Reads records from IST table.YYReads specified records from the IST table to specified buffer.
dc_ist_write
[CBLDCIST(WRIT)]
Writes records to IST table.YYWrites specified records to the IST table.
User journal collection (jnl)dc_jnl_ujput
[CBLDCJNL(UJPUT)]
Collects UAP log information.YY--
Lock of resources (lck)dc_lck_get
[CBLDCLCK(GET)]
Requests locking of resources.YY--
dc_lck_release_all
[CBLDCLCK(RELALL)]
Requests unlocking of all resources.YY--
dc_lck_release_byname
[CBLDCLCK(RELNAME)]
Requests unlocking of a specified resource.YY--
Message log control (log)dc_logprint
[CBLDCLOG(PRINT)]
Requests logged message output.YY--
Message control function (mcf)dc_mcf_execap
[CBLDCMCF(EXECAP)]
<SEND>
Starts an application.YY--
dc_mcf_mainloop
[CBLDCMCF(MAINLOOP)]
Starts the MCF service.YYNotifies the offline tester that MCF service has started. At a service request to the MHP, executes the service function and waits for the next service request. Returns when a UAP termination request is received (at offline tester termination, for example).
dc_mcf_receive
[CBLDCMCF(RECEIVE)
]<RECEIVE>
Message receiveYYInputs a segment from the MCF receive message file and stores the segment in the message receive area. Counts up the transaction sequence number.
dc_mcf_reply
[CBLDCMCF(REPLY)]
<SEND>
Response message sendYY--
dc_mcf_rollback
[CBLDCMCF(ROLLBACK)]
<ROLLBACK>
Partial recoveryYYCounts up the transaction sequence number if the next processing is specified to run as a different transaction.
dc_mcf_send
[CBLDCMCF(SEND)]
<SEND>
Message sendYY--
dc_mcf_open
[CBLDCMCF(OPEN)]
Prepares and initializes for using the MCF service.YY--
dc_mcf_close
[CBLDCMCF(CLOSE)]
Deletes the environment for using the MCF service.YN--
dc_mcf_sendrecv
[CBLDCMCF(SENDRECV)]
<SEND>
Synchronous message send/receiveYYOutputs trace information of the last segment, then inputs a segment from the MCF receive message file and stores the segment in the message receive area.
dc_mcf_recvsync
[CBLDCMCF(RECVSYNC)]
<RECEIVE>
Synchronous message receiveYYInputs a segment from the MCF receive message file and stores the segment in the message receive area.
dc_mcf_sendsync
[CBLDCMCF(SENDSYNC)]
<SEND>/<ENABLE>/<DISABLE>
Synchronous message sendYY--
dc_mcf_tempget
[CBLDCMCF(TEMPGET)]
<RECEIVE>
Passes temporary memory data for continuous inquiry/responseYYInputs data from the temporary memory data file and stores the data in the message receive area. Or, stores a null character if no file exists.
dc_mcf_tempput
[CBLDCMCF(TEMPPUT)]
<SEND>
Updates temporary memory data for continuous inquiry/responseYYUpdates the temporary memory data file. Or, creates an update file if none exists.
dc_mcf_contend
[CBLDCMCF(CONTEND)]
<DISABLE>
Terminates continuous inquiry/responseYYDeletes the temporary memory data file.
dc_mcf_regsterSets user exit routine function addresses.YY--
dc_mcf_resend
[CBLDCMCF(RESEND)]
Message resendYY--
dc_mcf_commit
[CBLDCMCF(COMMIT)]
Synchronous point acquisitionYYCounts up the transaction sequence number.
Remote procedure call (rpc)dc_rpc_call
[CBLDCRPC(CALL)]
Remote service callYYRequests the offline tester to execute a service function.
Returns a descriptor (positive integer) as the return value when DCRPC_NOWAIT is specified.
Or, returns zero to the specified service (service function) as the response length when DCRPC_NOREPLY is specified.
dc_rpc_close
[CBLDCRPC(CLOSE)]
UAP terminationYN--
dc_rpc_mainloop
[CBLDCRSV(MAINLOOP)]
Starts the SPP service.YYNotifies the offline tester that service has started. At a service request to the SPP, executes the service function and waits for the next service request. Returns when a UAP termination request is received (at offline tester termination, for example).
dc_rpc_open
[CBLDCRPC(OPEN)]
UAP start processingYYAllocates shared memory, then notifies the offline tester that the UAPs have started.
dc_rpc_poll_any_replies
[CBLDCRPC(POLLANYR)]
Receives responses from the dc_rpc_call function (DCRPC_NOWAIT specified).YYIf flags=DCNOFLAGS, returns the descriptor of the first dc_rpc_call function (DCRPC_NOWAIT specified) for which no reply was received. If flags=DCRPC_SPECIFIC_MSG, returns DC_OK. If no dc_rpc_call functions that terminated normally were issued in the SPP, returns DCRPC_PROTO.
dc_rpc_discard_further_replies
[CBLDCRPC(DISCARDF)]
Cancels responses from the dc_rpc_call function (DCRPC_NOWAIT specified).YNCancels all descriptors returned by the dc_rpc_call function (DCRPC_NOWAIT specified).
dc_rpc_get_callers_address
[CBLDCRPC(GETCLADR)]
Notifies the node address of the client.YNReturns ADDRESS (fixed value) as the client address.
dc_rpc_set_service_prio
[CBLDCRPC(SETSVPRI)]
Sets schedule priority of service requests.YN--
dc_rpc_get_service_prio
[CBLDCRPC(GETSVPRI)]
Gets schedule priority of service requests.YNReturns the schedule priority value specified for the dc_rpc_set_service_prio function.
dc_rpc_set_watch_time
[CBLDCRPC(SETWATCH)]
Updates the service response wait time.YYUpdates the service response wait time.
dc_rpc_get_watch_time
[CBLDCRPC(GETWATCH)]
References the service response wait time.YNReferences the values set by the dc_rpc_set_watch_time function. Returns 180 if the function has not been issued.
TAM file service (tam)dc_tam_closeCloses a TAM table.YYReleases lock and closes the TAM table.
dc_tam_delete
[CBLDCTAM(ERS or ERSR)]
Deletes a record from a TAM table.YYDeletes a record specified by key value from a TAM table and updates the TAM table file.
dc_tam_get_inf
[CBLDCTAM(GST)]
Collects TAM table information.YYReturns DCTAM_STS_OPN if the calling process has issued an open request for the specified TAM table file. Or, returns DCTAM_STS_CLS if no open request has been issued.
dc_tam_openOpens a TAM table.YYOpens the TAM table specified by table ID and returns the file ID as the table ID. Locks the TAM table file if lock of the TAM table is specified.
dc_tam_read
[CBLDCTAM(FxxR or FxxU)]
Retrieves a record from a TAM table.YYRetrieves a specified index from a TAM table (control part and index part) in shared memory and reads the record for the index from the TAM table file. Locks the TAM table file if lock of the record is specified.
dc_tam_read_cancelCancels TAM table record retrieval.YYUnlocks the TAM table file that contains a specified record.
dc_tam_rewriteUpdates a retrievable record in a TAM table.YYWrites the contents of a specified buffer to a specified record in a TAM table.
dc_tam_write
[CBLDCTAM(MFY, MFYS, or STR)]
Updates or appends a record in a TAM table.YYRetrieves a specified index from a TAM table (control part and index part) in shared memory and writes the contents of a specified buffer to the record for the index in the TAM table file.
Transaction control (trn)dc_trn_begin
[CBLDCTRN(BEGIN)]
Starts a transaction.YYCounts up the transaction sequence number.
dc_trn_chained_commit
[CBLDCTRN(C-COMMIT)]
Commits a transaction (chained mode).YYCounts up the transaction sequence number.
dc_trn_chained_rollback
[CBLDCTRN(C-ROLL)]
Rolls back a transaction (chained mode).YYCounts up the transaction sequence number.
dc_trn_info
[CBLDCTRN(INFO)]
Returns information for the current transaction.YYReturns zero if no information is specified in the function return values file.
dc_trn_unchained_commit
[CBLDCTRN(U-COMMIT)]
Commits a transaction (unchained mode).YY--
dc_trn_unchained_rollback
[CBLDCTRN(U-ROLL)]
Rolls back a transaction (unchained mode).YY--
TX interface (tx_~)tx_begin
[TXBEGIN]
Starts a transaction.YYCounts up the transaction sequence number and initializes TXINFO information.
tx_close
[TXCLOSE]
Closes the resource managers.YY--
tx_commit
[TXCOMMIT]
Commits a transaction.YYIn chained mode, counts up the transaction sequence number.
tx_info
[TXINFORM]
Returns information for the current transaction.YYReturns zero if no information is specified in the function return values file.
tx_open
[TXOPEN]
Opens the resource managers.YY--
tx_set_commit_return
[TXSETCOMMITRET]
Sets commit_return characteristics.YY--
tx_set_transaction_control
[TXSETTRANCTL]
Sets trans-action_control characteristics.YYSets transaction_control characteristics.
tx_set_transaction_timeout
[TXSETTIMEOUT]
Sets trans-action_timeout characteristics.YY--
tx_rollback
[TXROLLBACK]
Rolls back a transaction.YYIn chained mode, counts up the transaction sequence number and sets transaction_state characteristics.
XATMI interface (tp_~)tpallocAllocates a typed buffer.YYAllocates the buffer specified by an argument of type type and returns the pointer.
tpfreeFrees a typed buffer.YNFrees the buffer allocated by the tpalloc or tprealloc function.
tpreallocResizes a typed buffer.YYResizes the buffer allocated by the tpalloc or tprealloc function.
tptypesGets typed buffer information.YYReturns the type and subtype of the buffer allocated by the tpalloc or tprealloc function.
tpserviceService function templateYNCollects trace information immediately before a service function is called.
tpreturnReturns from a service function.YYSets return information and returns to the client UAP.
tpadvertiseAdvertises a service name.YY--
tpunadvertiseCancels service name advertising.YY--
tpacallAsynchronous service requestYYRequests the offline tester to execute a service function. The tpgetrply function returns the call result.
tpcallSynchronous service requestYYRequests the offline tester to execute a service function.
tpcancelService cancellationYYCancels the response from the service requested by tpacall function.
tpgetrplyAsynchronous response from a serviceYYReturns the execution result of a service function.
tpconnectEstablishes the conversational service paradigm connection.YYRequests the offline tester to execute a service function. The execution result is returned by the tprecv function.
tpdisconDisconnects the conversational service paradigm.YYTerminates the service if in reply wait state (tprecv function) and disables acceptance of tpsend or tprecv after the tpdiscon is accepted.
tprecvMessage receive from the conversational service paradigmYYInputs data from the XATMI receive data file.
tpsendMessage send to the conversational service paradigmYYOutputs data to the XATMI send data file.
Online tester (uto)dc_uto_test_status
[CBLDCUTO(T-STATUS)]
Reports user server test state.YYReturns non-test mode state.
Legend:
Y: Trace information collected; return value set.
N: Trace information cannot be collected; return value cannot be set.
--: No processing

(2) Notes on simulation functions

Note the following points on using the function simulator:

  1. The offline tester does not check the type of the UAP issuing the function, transaction status, or whether the function is issued inside or outside the main function.
  2. The function sequence is checked only for functions that affect offline tester operation.
  3. Arguments are not checked. The user should check the arguments from the trace information.
  4. An error message is output but no trace information is collected when an interface code or request code is set incorrectly in a COBOL program.
  5. A dc_trn_~ function cannot coexist with a tx_~ function. The offline tester does not check whether the two functions types are mixed.
  6. The offline tester counts the number of transactions (transaction sequence number). The transaction sequence number is counted up at execution of some simulation functions and at execution of the call subcommand. You can reference the transaction sequence number by using the tx_info function. For details about the simulation function that increments the transaction sequence number, see (1) Simulation functions, above.