Hitachi

JP1 Version 11 JP1/Script Description and Reference (For Windows Systems)

8.10.5 CallSpt (call a script file with multiple parameters set)

Purpose

Calls a script file (.SPT file) with multiple parameters set. Unlike the Exec command, the called script file is executed within the current process.

Syntax
CallSpt (SptFileName [, Param1, Param2, ... ,Param31])
Arguments
SptFileName

Specify the name of the JP1/Script script file (.SPT) as a character string, or as a variable that stores this value. The extension .SPT is appended automatically if omitted.

Param1 to Param31

Specify the necessary parameters for executing the file specified in SptFileName. Write each parameter as a string or number, or as a variable that stores this value.

Alternatively, you can specify a one-dimensional array variable that stores all the required parameters. For parameter coding conventions, see 6.2.3 Command line coding conventions.

To include n double quotation marks (") as characters in a parameter, write n*2 double quotation marks, and enclose the entire parameter with double quotation marks.

If specified in the CallSpt command, the /SPT:HIDE, /SPT:MIN, and /SPT:MAX parameters, which have a special meaning in the Exec and NetExec commands, and the /SPALV(n), /SPXLV(n), and /NOEVLOG parameters are passed as command line parameters and handled as character strings. They have no special meaning in this command.

Description

The CallSpt command executes a specified script file.

Unlike the Exec command, a script file called by the CallSpt command is executed within the current process. The script file therefore behaves like a procedure, sharing the environment of the current process and able to update the process environment variable.

The following variable and procedure relationships apply between a script file that executes the CallSpt command (hereafter, parent script) and a script file specified in the SptFileName argument (hereafter, child script):

  • Variables that are explicitly declared in a child script, using the Dim command or equivalent, behave as local variables that are valid only within that child script.

  • Variables that are used but not explicitly declared in a child script are also local, unless they are defined in the parent script before the CallSpt command is invoked, or in a parent script at a level higher than the calling parent script. A variable defined in this way outside the child script is handled as a global variable.

  • Procedures defined within the parent script, or in a higher-level parent script, can also be used within the child script.

  • When procedures of the same name are defined in the parent script and child script, the procedure defined in the child script is valid in that script. However, if the two procedures are Function and Sub, respectively, the Function procedure defined in the parent script is valid in the child script.

  • Local variables and procedures defined in the child script, and location variables for the child script, are discarded when the child script completes execution (at termination of the CallSpt command in the parent script).

  • Variables and procedures defined in the parent script cannot be used when executing the child script as an independent process.

Child scripts are executed according to the parameters specified for the parent script. Any #FileVersion or #Option setting in the child script is ignored. The settings in the child script's execution environment file (.SPV) do not apply.

The command returns True on successful execution, or False if an error occurs. If the execution result is True, the script file's exit code is stored as a signed numeric in the _EXEC_RTN_ reserved variable.

Notes

  • Unlike other commands, the syntax of the script file specified in SptFileName is also examined when you perform a syntax check of the CallSpt command.

  • Null characters specified in parameters are ignored. To omit a parameter, specify, for example, an explicit string that will be passed from the calling script to the called script. See Example 2.

  • If a string containing spaces is specified for a parameter, the parameter is passed to the called script as a single string delimited by spaces. In this case, enclose the entire string containing spaces in double quotation marks ("). However, you need to remove the double quotation marks (") from the parameters received at the called script. See Example 3.

    Important note

    • The Exit command executed in a script called by the CallSpt command simply terminates execution of that script and returns control to the calling script. Execution of the calling script is not terminated.

    • The Skip specification in the Option argument of the Exit command is valid if you terminate the script without waiting for completion of an executable file called by the Exec or NetExec command. In this case, to terminate the script from a script file called by the CallSpt command, specify Skip in the Option argument of the Exit command for a script file that executes the CallSpt command. The script will not terminate if you specify Skip in the Option argument of the Exit command for a script file that executes the Exec or NetExec command. For details, see Example 4.

Example 1
' Execute the script file "Environment.SPT", and reference
' and update the process environment variable.
Dim Path01
rtn = CallSpt(_SCF_+"Environment.SPT", "Get", "Path01", _
              Path01)
      ...
rtn = CallSpt(_SCF_+"Environment.SPT", "Set", "Path01", _
 _            TEMP_)
 
' Environment.SPT processing
Select Case %1
Case "Set"
   SetEnv(ProcessEnv, %2, %3)
Case "Get"
   %3 = GetEnv(ProcessEnv, %2)
End Select
Example 2

In the specification shown below, the NULL parameter (null character "") of the CallSpt command in the calling script is ignored.

The location variables, where "B" is stored in %1 and "D" is stored in %2, are passed to the called script.

Calling script
CallSpt("A.spt", "B", "", "D")
Called script
Parm1 = %1  ' "B"
Parm2 = %2  ' "D"
Parm3 = %3  ' null character""

To omit a parameter, specify, for example, an explicit string that will be passed from the calling script to the called script as shown below.

Calling script
Dim C_Parm
If ... Then
    C_Parm="C"
Else
    C_Parm="***NOTPARAMETA***"
End If
CallSpt("A.spt", "B", C_Parm, "D")
      :
Called script
If %2 <> "***NOTPARAMETA***" Then
    Parm1 = %1 ' "B"
    Parm2 = %2 ' "C"
    Parm3 = %3 ' "D"
Else
    Parm1 = %1 ' "B"
    Parm2 = "" ' Null characters""
    Parm3 = %3 ' "D"
End If

The number of arguments used when the function was called is stored in the _ARGV_CNT_ reserved variable. If you want to check whether any arguments are omitted, use _ARGV_CNT_.

Example 3

In the specification shown below, the location variables in the calling script are as follows: "My" is stored in %1, "Documents" is stored in %2, and "Files" is stored in %3. 

    CallSpt("A.spt", "My Documents", "Files")

To specify a parameter containing spaces, enclose the entire string in double quotation marks (") and pass it to the called script. Note that because the string containing double quotation marks is passed to the called script, you need to remove the double quotation marks from the parameter as shown below.

Calling script
CallSpt("A.spt", """My Documents""", "Files")
      :
Called script
Dim Parm1
Dim Path1
  Parm1= Mid (%1, 2, Len (%1) - 2)
  Path1 = Parm1 + "\" + %2
      :
Example 4

Terminate the calling script without waiting for completion of the called executable file.

Calling script: SampleA.SPT
' Call the Script file "SampleB.SPT".
CallSpt(_SCF_+"SampleB.SPT")
    :
' Terminate the script without waiting for completion of 
' SampleC.EXE.
Exit(0,Skip)
Called script: SampleB.SPT
' Call the executable file"SampleC.EXE" but do not wait 
' for its termination.
Exec(_SCF_+"SampleC.EXE",False)
JP1/Script version

Supported from JP1/Script 06-71.

To Page Top

Trademarks

Copyright (C) 2016, Hitachi, Ltd.

Copyright (C) 2016, Hitachi Solutions, Ltd.