TRIPsystem Kernel API 8.3
Loading...
Searching...
No Matches
Procedure Management

Managementr of TRIP stored procedures. More...

Functions

int TdbClearRunStack (void)
 Clear the stack of running procedures, effectively doing a jump from any nesting level back to the top.
 
int TdbContinue (void)
 Check if continuation on error has been defined.
 
int TdbCopyProcedure (char *oldProcedure, char *newProcedure)
 Create a copy of a procedure.
 
int TdbDeleteProcedure (char *procedure)
 Delete a TRIP macro/procedure.
 
int TdbGetNextProcLine (char **line, int *length)
 Returns the next line to be executed out of a procedure.
 
int TdbGetProcedure (char *procedure)
 Load a TRIP macro or procedure.
 
int TdbGetProcLine (char *line, int *lineLength)
 Load a macro/procedure line.
 
int TdbPutProcedure (void)
 Store a TRIP macro or procedure.
 
int TdbPutProcLine (char *line, int lineLength)
 Load a macro/procedure line into an internal buffer.
 

Detailed Description

Managementr of TRIP stored procedures.

Functions in the procedure management group provides access to TRIP procedure manipulation and execution. A TRIP procedure is a named sequence of stored CCL commands, callable with the CCL RUN command.

Function Documentation

◆ TdbClearRunStack()

int TdbClearRunStack ( void  )

Clear the stack of running procedures, effectively doing a jump from any nesting level back to the top.

Returns
1 or other odd value on success, even value on error

Description

The function TdbClearRunStack() is used to terminate the execution of a procedure when an error occurs. This would normally be used in conjunction with the TdbContinue() function to ensure that the procedure is only terminated if the calling process has not specified DEfine CONTinue.

Note
If the calling process is operating in interactive mode, the stack is cleared completely; if the calling process is operating in batch mode, the stack is unwound only one level.
See also
TdbContinue()

◆ TdbContinue()

int TdbContinue ( void  )

Check if continuation on error has been defined.

Returns
1 or other odd value on success, even value on error

Description

The function TdbContinue() is used to check if execution of commands in a procedure is to continue when an error is detected. If this routine returns a success code, then the procedure should continue; otherwise, the calling process should call the function TdbClearRunStack() to return to the top level of processing.

Return Codes

 Code Description Explanation
1 Procedure execution may continue.
0 Do not continue to execute the procedure.
See also
TdbClearRunStack()

◆ TdbCopyProcedure()

int TdbCopyProcedure ( char *  oldProcedure,
char *  newProcedure 
)

Create a copy of a procedure.

Parameters
oldProcedureName of source procedure
newProcedureName of new procedure
Returns
1 or other odd value on success, even value on error

Description

The function TdbCopyProcedure() starts the copying of a procedure from one name to another or from one user to a different user or group, if the security subsystem allows it. The calling process must call TdbPutProcedure() to commit the new procedure to the CONTROL database.

Parameter Values

The oldProcedure parameter is passed the name of the procedure to be copied.

The newProcedure parameter is passed the name the new procedure. The maximum length of a procedure name is 16 characters. However, it may be qualified with the name of the user or group that is to stand as the owner of the procedure. This means that both "VERYLONGPROCNAME" and "VERYLONGUSERNAME.VERYLONGPROCNAME" are valid.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
2402 Attempt to create an already existing procedure. A procedure with the target name already exists.
See also
TdbPutProcedure()

◆ TdbDeleteProcedure()

int TdbDeleteProcedure ( char *  procedure)

Delete a TRIP macro/procedure.

Parameters
procedureName of procedure
Returns
1 or other odd value on success, even value on error

Description

The function TdbDeleteProcedure() deletes the specified TRIP macro/procedure from the CONTROL file. The TRIP user ID for the current session must be the creator of the macro/procedure to be deleted.

Parameter Values

The procedure parameter is passed a character string as the name of the procedure to be deleted.

Return Codes

 Code Description Explanation
32899 Procedure id.procname deleted. The procedure was successfully deleted.
9026 Procedure/group name cannot be more than 16 characters each.
12706 Missing or invalid procedure name. An empty string or one with only white space is not valid as a name.
15618 Only alphanumerics/underscores allowed in names.
2370 Attempt to delete a non existent procedure.
9698 No such group as group. The current user is not the owner of the procedure, and the group that is the owner of the procedure could not be found.
10466 Group is not a group id. The current user is not the owner of the procedure, and the registered procedure owner is not a group.
9730 You are not the creator of the group group. If the procedure is owned by a group, only the user which is the creator of the group may delete the procedure.

◆ TdbGetNextProcLine()

int TdbGetNextProcLine ( char **  line,
int *  length 
)

Returns the next line to be executed out of a procedure.

Parameters
lineProcedure or macro line.
lengthLength of returned line parameter.
Returns
1 or other odd value on success, even value on error

Description

Returns the next line to be executed out of a procedure.

This function should be called subsequent to the exection of a CCL RUN command. It differs from the old TRIPapi function, TdbNextRunCommand() in that it takes other arguments allowing for an unlimited length of a CCL order.

Parameter Values

The line parameter receives the next macro or procedure line to execute.

The length parameter recieves the length of the returned line.

Since

This function was introduced in TRIP version 3.4-0.

◆ TdbGetProcedure()

int TdbGetProcedure ( char *  procedure)

Load a TRIP macro or procedure.

Parameters
procedureProcedure or macro name
Returns
1 or other odd value on success, even value on error

Description

The function TdbGetProcedure() loads a TRIPsystem macro or procedure into an internal buffer for further processing. A procedure can only be loaded by its owner.

This function is intended primarily for use within the TRIPclassic environment.

Parameter Values

The procedure parameter is passed a character string as the name of a procedure name. The name may alternatively identify a macro.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
9698 No such group as group. The current user is not the owner of the procedure, and the group that is the owner of the procedure could not be found.
10466 Group is not a group id. The current user is not the owner of the procedure, and the registered procedure owner is not a group.
9730 You are not the creator of the group group. If the procedure is owned by a group, only the user which is the creator of the group may load the procedure.
2338 Procedure name not found. The procedure did not exist.
See also
TdbGetProcLine()
TdbPutProcLine()
TdbPutProcedure()

◆ TdbGetProcLine()

int TdbGetProcLine ( char *  line,
int *  lineLength 
)

Load a macro/procedure line.

Parameters
lineProcedure line
lineLengthLength of procedure line
Returns
1 or other odd value on success, even value on error

Description

The function TdbGetProcLine() loads a single line from a macro/procedure into the line parameter. The macro/procedure must have been previously loaded into the internal buffer by using the TdbGetProcedure(). Repeated calls to TdbGetProcLine() until a status code of zero is returned allows processing of the complete macro/procedure.

If a line exceeds the maximum length passed via the lineLength parameter, then it will be truncated and a hyphen appended to it. The next call to TdbGetProcLine() retrieves the rest of the line again truncating it as required. Note that the hyphen is added onto the maximum-length string, so the string may actually be one character longer than what was specified by the length argument on input.

Parameter Values

The line parameter receives the procedure line to be retrieved.

The lineLength parameter in the server version of this function receives the length of the returned procedure line. Before calling the function the lineLength argument must specify the maximum length of the string that is to be copied into the line buffer, including the terminating null-byte.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 Could not get procedure line. No more lines.
See also
TdbGetProcedure()

◆ TdbPutProcedure()

int TdbPutProcedure ( void  )

Store a TRIP macro or procedure.

Returns
1 or other odd value on success, even value on error

Description

The function TdbPutProcedure() stores a TRIPsystem macro or procedure in the CONTROL file. The call must have been preceded by a call to one of the TdbGetProcedure() or TdbCopyProcedure() functions.

Return Codes

 Code Description Explanation
32835 Procedure id.name altered. An existing procedure was successfully updated.
32867 Procedure id.name created. A new procedure was successfully created.
9538 No write access to the database CONTROL. The current user does not have write access to the CONTROL database.
9538 No write access to the database CONTROL. The current user does not have write access to the CONTROL database.
See also
TdbCopyProcedure()
TdbGetProcedure()

◆ TdbPutProcLine()

int TdbPutProcLine ( char *  line,
int  lineLength 
)

Load a macro/procedure line into an internal buffer.

Parameters
lineLine to add to procedure text
lineLengthLength of line
Returns
1 or other odd value on success, even value on error

Description

The function TdbPutProcLine() loads a single macro/procedure line into an internal buffer. The macro/procedure must have been loaded into the buffer by a call to either the TdbGetProcedure() or TdbCopyProcedure() function.

If the macro/procedure is not new, all existing lines must first be read by repeated calls to the TdbGetProcLine() function. The initial call to TdbPutProcLine() will then empty the buffer and make the supplied line the first in the macro/procedure, while subsequent calls append lines to ' the macro/procedure. It is for the application program to provide i ntermediate storage for the lines.

In order to store the macro/procedure the TdbPutProcedure() function has to be called.

Parameter Values

The line parameter is passed a character string as a line to add in the procedure's body.

The lineLength parameter is passed an integer as the length of the line being added.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
17122 CCL command line no number in command is too long.
See also
TdbCopyProcedure()
TdbGetProcLine()
TdbGetProcedure()
TdbPutProcedure()