TRIPsystem Kernel API 8.3
|
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. | |
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.
int TdbClearRunStack | ( | void | ) |
Clear the stack of running procedures, effectively doing a jump from any nesting level back to the top.
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.
int TdbContinue | ( | void | ) |
Check if continuation on error has been defined.
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.
Code | Description | Explanation |
---|---|---|
1 | Procedure execution may continue. | |
0 | Do not continue to execute the procedure. |
int TdbCopyProcedure | ( | char * | oldProcedure, |
char * | newProcedure | ||
) |
Create a copy of a procedure.
oldProcedure | Name of source procedure |
newProcedure | Name of new procedure |
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.
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.
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. |
int TdbDeleteProcedure | ( | char * | procedure | ) |
Delete a TRIP macro/procedure.
procedure | Name of procedure |
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.
The procedure
parameter is passed a character string as the name of the procedure to be deleted.
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. |
int TdbGetNextProcLine | ( | char ** | line, |
int * | length | ||
) |
Returns the next line to be executed out of a procedure.
line | Procedure or macro line. |
length | Length of returned line parameter. |
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.
The line
parameter receives the next macro or procedure line to execute.
The length
parameter recieves the length of the returned line.
This function was introduced in TRIP version 3.4-0.
int TdbGetProcedure | ( | char * | procedure | ) |
Load a TRIP macro or procedure.
procedure | Procedure or macro name |
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.
The procedure
parameter is passed a character string as the name of a procedure name. The name may alternatively identify a macro.
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. |
int TdbGetProcLine | ( | char * | line, |
int * | lineLength | ||
) |
Load a macro/procedure line.
line | Procedure line |
lineLength | Length of procedure line |
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.
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.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | Could not get procedure line. No more lines. |
int TdbPutProcedure | ( | void | ) |
Store a TRIP macro or procedure.
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.
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. |
int TdbPutProcLine | ( | char * | line, |
int | lineLength | ||
) |
Load a macro/procedure line into an internal buffer.
line | Line to add to procedure text |
lineLength | Length of line |
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.
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.
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. |