pdcomm_gem_formatted_program_transfer_submit

Function

Sends an S7F23 Formatted Process Program Send to the equipment.

PdcommStatus pdcomm_gem_formatted_program_transfer_submit(PdcommTcpEndpoint *endpoint, const PdcommSecsItem *id, const char *model, size_t model_length, const char *software_revision, size_t software_revision_length, const PdcommGemFormattedProgramTransferCommand *commands, size_t command_count, PdcommTcpToken *out_token)

Declared in: #include <pdcomm_gem_formatted_program_transfers.h>

Host only. The program is validated against the configured limits and copied before S7F23 is queued. Success means the message was accepted for sending; the S7F24 reply, a T3 timeout, or a disconnection is reported later through pdcomm_gem_handle_event() with the returned token.

Parameters

Name	Description
`endpoint`	Host endpoint in the GEM COMMUNICATING state.
`id`	PPID: a nonempty ASCII or Binary item of at most 120 bytes.
`model`	MDLN: at most 20 ASCII bytes. May be NULL when `model_length` is 0.
`model_length`	Length of `model` in bytes.
`software_revision`	SOFTREV: at most 20 ASCII bytes. May be NULL when `software_revision_length` is 0.
`software_revision_length`	Length of `software_revision` in bytes.
`commands`	Array of `command_count` process commands. Each CCODE must be an ASCII item. May be NULL when `command_count` is 0.
`command_count`	Number of commands.
`out_token`	Receives the transaction token. It is zeroed before any other check, so it is zero after every failure.

Returns

#PDCOMM_OK when S7F23 was queued; #PDCOMM_INVALID_ARGUMENT when out_token, endpoint, id, a CCODE, or a PPARM pointer is NULL, commands is NULL with a nonzero count, or the PPID, MDLN, SOFTREV, or a CCODE is invalid; #PDCOMM_INVALID_STATE when the endpoint is not a Host in the COMMUNICATING state or the service is not configured; #PDCOMM_BACKPRESSURE when a staged TCP event must be drained first, all 32 GEM request slots are in use, or the TCP send queue is full; #PDCOMM_LIMIT_EXCEEDED when a command or parameter limit is exceeded, an item exceeds the endpoint's SECS-II limits, or max_pending transfers are already waiting; other TCP statuses such as #PDCOMM_IO_ERROR when the message cannot be queued; #PDCOMM_POISONED when the endpoint is poisoned.

Notes

Ownership: all inputs stay owned by the caller.
Thread safety: serialize with every other call on endpoint.