SCA Command Reference

Table 4‑1 lists SCA commands and functions.

 

Table 4‑1 Oracle Tuxedo Commands and Functions

Name	Description
buildscaclient	Builds processes that call SCA components.
buildscacomponent	Builds SCA components.
buildscaserver	Parses SCDL definitions and interfaces and produces a Tuxedo-deployable server and elements.
mkfldfromschema, mkfld32fromschema	The mkfldfromschema and mkfld32fromschema commands take an XML schema as input and produce a field table.
mkviewfromschema, mkview32fromschema	The mkviewfromschema and mkview32fromschema commands take an XML schema as input and produce a view file.
scaadmin	SCA server management command interpreter.
SCAHOST (5)	Generic server for Python, Ruby, or PHP components.
scapasswordtool	Manages passwords for Oracle Tuxedo authentication in SCA clients.
scastructc32, scastructc(1)	Oracle Tuxedo structure description file compiler
scastructdis32, scastructdis	Binary structure and view files disassembler.
scatuxgen(1)	Generates Oracle Tuxedo Service Metadata Repository interface information from an SCA interface.
setSCAPasswordCallback(3c)	Sets the callback for retrieving a password associated with an identifier in a <binding.atmi> element.
tuxscagen(1)	Generates SCA, SCDL, and server-side interface files for Tuxedo services.

buildscaclient

Name

buildscaclient – Builds processes that call SCA components.

Synopsis

buildscaclient -c default_component [-v] [-h] [-k] [-o name] [-s SCAroot] [-f firstfiles] [-l lastfiles] [-S structurefiles]

Description

This command is used to build client processes that can call SCA components hosted in Tuxedo environments. The command combines files, specified using the -f and -l options, with the SCA and standard Tuxedo ATMI libraries to form a client application. The client application is built using the default C++ language compile command defined for the operating system in use, unless overridden using the CC environment variable.

All specified .c and .cpp files are compiled in one invocation of the compilation system based on the operating system. Users may specify the compiler to invoke by setting the CC environment variable to the name of the compiler. If the CC environment variable is not defined when buildscaclient is invoked, the default C++ language compile command for the operating system is invoked to compile all .c and .cpp files.

You may specify additional options to be passed to the compiler by setting the CFLAGS or the CPPFLAGS environment variables. If CFLAGS is not defined when buildobjclient is invoked, then buildscaclient uses the value of CPPFLAGS, if that variable is defined.

Parameters and Options

buildscaclient supports the following parameters and options:

-c defaultcomponent

Required parameter. Indicates which component should be used for this application.

[-v]

Specifies that the buildscaclient command should work in verbose mode. In particular, it writes the compile command to its standard output.

[-k]

Maintains the generated stubs. buildscaclient generates proxy files that allow dynamic interfacing of clients and references. This is normally compiled and then removed when the proxy is built. This option indicates that the source file should be retained.

Caution:

The generated contents of this file may change from release to release. It is advised that you do not depend on the data structures and interfaces exposed in this file. This option is provided to aid in debugging of build problems.

[-o name]

Specifies the name of the client application generated by this command. If the name is not supplied, the application file is named client<.type>, where type is an extension that is dependent on the operating system. For example, on a UNIX system, there would not be a type, but on a Windows system, the type would be .EXE.

[-s scaroot]

Specifies the location of SCA root, where the SCDL files for the required components are located. If not set, the APPDIR environment value is used.

[-f firstfiles]

Specifies the file to be included first in the compile and link phases of the buildscaclient command. The specified file is included before the SCA libraries are included. There are two ways of specifying a file or files:

 

Filename Specification	Description
-f firstfile	One file is specified
-f "file1.cpp file2.cpp file3.cpp … "	Multiple files may be specified if their names are enclosed in quotation marks and are separated using white spaces.

Note:

Filenames that include spaces are not supported. The -f option may be specified multiple times.

[-l lastfiles]

Specifies a file to be included last in the compile and link phases of the buildscaclient command. The specified file is included after the SCA libraries are included. There are two ways of specifying the file, as shown in the following table.

 

Filename Specification	Description
-l lastfile	One file is specified
-l "file1.cpp file2.cpp file3.cpp … "	Multiple files may be specified if their names are enclosed in quotation marks and are separated using white spaces.

Note:

Filenames that include spaces are not supported. The -l option may be specified multiple times.

[-S structurefiles]

Specifies an SCA structure description file. The structure description file may be either a source file or a binary structure description file. If more than one file is specified, file names must be separated by white space and the entire list must be enclosed in quotation marks. The -S option may be specified multiple times on the same command line.

The use of structure description files is optional. If a structure description is not provided for a particular structure then the source code where the structure is defined is used describe the structure; in SCA-ATMI mode, the FML32 field name corresponding to each structure element is the same as the name of the structure element.

Note:

Filenames that include spaces are not supported. The -S option may be specified multiple times.

Environment Variables

Following is a list of environment variables for buildSCAclient:

TUXDIR

Finds the SCA libraries and includes files to use when compiling the client applications.

CC

Indicates the compiler for all files with .c or .cpp file extensions. If not defined, the default C++ language compile command is invoked to compile all .c and .cpp files, based on the operating system.

CFLAGS

Indicates any arguments that are passed as part of the compiler command line for any files with .c or .cpp file extensions. If CFLAGS does not exist in the buildscaclient command environment, the command checks for the CPPFLAGS environment variable.

Note:

Arguments passed by the CFLAGS environment variable take priority over the CPPFLAGS variable.

CPPFLAGS

Contains a set of arguments that are passed as part of the compiler command line for any files with .c or .cpp file extensions.

This is in addition to the command line option "-I$(TUXDIR)/include" for UNIX systems or the command line option /I%TUXDIR%\include for Windows systems, which is passed automatically by the buildscaclient command. If CPPFLAGS does not exist in the buildscaclient command environment, no compiler commands are added.

LD_LIBRARY_PATH (UNIX systems)

Indicates the directories that contain shared objects to be used by the compiler, in addition to the objects shared by the CORBA software. A colon (:) is used to separate the list of directories. Some UNIX systems require different environment variables:

•	HP-UX systems use the SHLIB_PATH environment variable

•	AIX systems use LIBPATH

LIB (Windows systems)

Indicates a list of directories that contain the library files. A semicolon (;) is used to separate the list of directories.

Portability

This utility can be used on any platform that supports the Oracle Tuxedo environment.

Example(s)

buildscaclient -s /myApplication/scaSrc/uBike -c uBike.client -f uBikeClient.cpp -o uBikeClient

See Also

[-S],

buildscacomponent

Name

buildscacomponent - builds SCA components

Synopsis

buildscacomponent [-v] [-s scaroot] [-f firstfiles] [-l lastfiles] [-S structurefiles] -c compositename[/componentname][,compositename,..]] [-y] [-k] [-h]

Description

buildscacomponent is used to build individual SCA components from source code. The command reads SCDL source, finds the component(s) in the composite(s) file(s) specified, parses the corresponding .componentType file(s) and produces corresponding executable libraries, in the same location as the .componentType files.

The command automatically builds component implementations based on the contents of <implementation.cpp> elements as follows:

•	The value of /implementation.cpp/@header is used to determine the name of the source and componentType files containing the implementation.

For example, an element such as

<implementation.cpp library="myLib" header="myComponentImpl.h"/>

causes buildscacomponent to look for a myComponentImpl.cpp file and compile it, along with stubs generated from its interface located in a corresponding myComponentImpl.componentType file.

Composites may contain one or more components, and the buildscacomponent command may build one or more composites in one pass. If more than one component is built, the files specified using the -f and -l switches are included in each component. To build a single component, the -c composite/component syntax should be used. This addresses the cases where individual components are made up of specific sets of source code or libraries.

All specified .c and .cpp files are compiled in one invocation of the compilation system for the operating system in use. Users may specify the compiler to be invoked by setting the CC environment variable to the name of the compiler. If the CC environment variable is not defined when buildscacomponent is invoked, the default C++ language compile command for the operating system in use is invoked to compile all .c and .cpp files.

Users may specify options to be passed to the compiler by setting the CFLAGS or the CPPFLAGS environment variable. If CFLAGS is not defined but CPPFLAGS is defined when buildscacomponent is invoked, the CPPFLAGS value is used.

Parameters and Options

buildscacomponentsupports the following parameters and options:

[-v]

Specifies that buildscacomponent should work in verbose mode.

[-s scaroot]

Specifies the location of the SCA root, where the SCDL file(s) for the component(s) is (are) located, and where the source code of components is processed.

If not specified, the value of APPDIR is used.

[-f firstfiles]

Specifies a file to be included first in the compile and link phases of the buildscacomponent command. The specified file is included before the SCA libraries are included. There are two ways of specifying a file or files, as shown in the following table.

 

Table 4‑2 File Specification Using [-f firstfiles]

Filename Specification	Definition
-f firstfile	One file is specified
-f "file1.cpp file2.cpp file3.cpp … "	Multiple files may be specified if their names are enclosed in quotation marks and are separated by white space.

Note:

Filenames that include spaces are not supported. The -f option may be specified multiple times.

[-l lastfiles]

Specifies a file to be included last in the compile and link phases of the buildscacomponent command. The specified file is included after the SCA libraries are included. There are two ways of specifying a file, as shown in the following table.

 

Table 4‑3 File Specification Using [-l lastfiles]

Filename Specification	Definition
-l lastfile	One file is specified
-l "file1.cpp file2.cpp file3.cpp … “	Multiple files may be specified if their names are enclosed in quotation marks and are separated by white space.

Note:

Filenames that include spaces are not supported. The -l option may be specified multiple times.

-c {composite[,composite]|composite/component}

Specifies the name(s) of the composite(s) processed. The composite(s) is (are) searched in APPDIR or in the SCDL directory specified above with the -s switch. If it cannot be found, the component libraries are not built.

A list of composites may be specified, in which case all the components listed in the composites will be built. If any of the composites cannot be found or an error is detected (incorrect name, composite does not have any ATMI service binding), a warning message is displayed and the user is prompted to confirm whether the command should continue processing or abort.

If the composite/component notation is used, a single component contained in the specified composite is allowed. This notation covers the situation where specific source files specified with -f and -l need to be included in the build process of a component.

[-y]

Optionally forces processing of input files, automatically ignoring warnings, such as composites specified using the -c switch but not physically present from the root directory.

[-k]

Keeps the generated proxy and wrapper source. buildscacomponent generates proxy and wrapper code with data structures such as the method operation and parameter handling. This is normally compiled and then removed when the component is built. This option indicates that the source file should be kept (to see what the source filename is, use the -v option).

Note:

The generated contents of this file may change from release to release. Do Not count on the data structures and interfaces exposed in this file. This option is provided to aid in debugging of build problems.

[-S structurefiles]

Specifies an SCA structure description file. The structure description file may be either a source file or a binary structure description file. If more than one file is specified, file names must be separated by white space and the entire list must be enclosed in quotation marks. The -S option may be specified multiple times on the same command line.

The use of structure description files is optional. If a structure description is not provided for a particular structure then the source code where the structure is defined is used describe the structure; in SCA-ATMI mode, the FML32 field name corresponding to each structure element is the same as the name of the structure element.

Note:

Filenames that include spaces are not supported. The -S option may be specified multiple times.

Environment Variables

TUXDIR

Finds the SCA libraries and include files to use when compiling the client applications.

APPDIR

Indicates the SCA application root location, where the top-level composite should reside.

CC

Indicates the compiler to use to compile all files with .c or .cpp file extensions. If not defined, the default C++ language compile command for the operating system in use will be invoked to compile all .c and .cpp files.

CFLAGS

Indicates any arguments that are passed as part of the compiler command line for any files with a .c or .cpp file extensions. If CFLAGS does not exist in the buildscacomponent command environment, the buildscacomponent command checks for the CPPFLAGS environment variable.

CPPFLAGS

Note:

Arguments passed by the CFLAGS environment variable take priority over the CPPFLAGS variable.

Contains a set of arguments that are passed as part of the compiler command line for any files with a .c or .cpp file extensions.

This is in addition to the command line option -I$(TUXDIR)/include for UNIX systems or the command line option /I%TUXDIR%\include for Windows systems, which is passed automatically by the buildscacomponent command. If CPPFLAGS does not exist in the buildscacomponent command environment, no compiler commands are added.

LD_LIBRARY_PATH (UNIX systems)

Indicates which directories contain shared objects to be used by the compiler, in addition to the objects shared by the CORBA software. A colon (:) is used to separate the list of directories. Some UNIX systems require different environment variables: for HP-UX systems, use the SHLIB_PATH environment variable; for AIX, use LIBPATH.

LIB (Windows systems)

Indicates a list of directories within which to find libraries. A semicolon (;) is used to separate the list of directories.

Portability

This utility can be used on any platform that supports the Oracle Tuxedo environment.

Example(s)

buildscacomponent -f utils.c -c searchInventory,updateItem

See also

[-S],Filenames that include spaces are not supported. The -f option may be specified multiple times.

buildscaserver

Name

buildscaserver – Builds an Oracle Tuxedo server containing SCA components.

Synopsis

-o servername -c composite[,composite][-v][-s scaroot]
[-w] [-r rmname][-y] [-k] [-t] [-S]

Description

buildscaserver is used to build a Tuxedo server that is used to route requests to SCA components previously built with the buildscacomponent command. The command generates a main routine that contains bootstrap routines to route Tuxedo or SCA requests to SCA components, and compiles it to form a server host application. The server host application is built using the default C++ compiler provided for the platform.

If the SCDL code contains references or services with <binding.ws> elements, these are automatically converted into WSDF files for use by the Web Services gateway (GWWS). All SCA servers built using buildscaserver are multi-threaded servers.

Parameters and Options

buildscaserver supports the following parameters and options:

-o servername

Required. Specifies the name of the server application generated by this command.

-c compositename[,compositename]

Required. Specifies the name of the composite hosted. The composite is searched for starting in APPDIR, or in the SCDL directory specified above with the -s switch. If it is not found, the server is not built. In case you specify a list of composites, then all the listed composites are hosted by the same Tuxedo server.

If any of the composites are not found or an error is detected such as incorrect name or composite does not have any atmi service binding, a warning message is displayed and the user is prompted to confirm whether the command should continue processing or abort.

[-v]

Specifies that buildscaserver should work in verbose mode.

[-s scaroot]

Specifies the target location of the SCA root, where the SCDL files for the components to be deployed are located.

This directory has a layout suitable to SCA composites and components. Each composite is represented as a directory and contains components in the run-time form, which includes SCDL code and libraries. At run time, the server application uses this directory to find the run-time SCA components.

If components are using the Web Services binding, the root location also receives a WSDF definition file.

[-w]

Specifies that the generated server will host Web services binding enabled components. By default, a server hosting ATMI binding enabled components is generated. Both types of servers can host the same actual components simultaneously (i.e. there can exist an ATMI and a WS servers, both hosting the same components previously built using the buildscacomponent command).

[-r rmname]

Specifies the resource manager associated with this server. The value rmname must appear in the resource manager table located in $TUXDIR/udataobj/RM on UNIX systems or %TUXDIR%\udataobj\RM on Windows systems. Each entry in this file is of the following form:

rmname:rmstructure_name:library_names

Using the rmname value, the entry in $TUXDIR/udataobj/RM or %TUXDIR%\udataobj\RM automatically includes the associated libraries for the resource manager and sets up the interface between the transaction manager and the resource manager. The value TUXEDO/SQL includes the libraries for the Oracle Tuxedo System/SQL resource manager. Other values can be specified once they are added to the resource manager table. If the -r option is not specified, the null resource manager is used, by default.

[-y]

Optionally forces processing of input files, automatically ignoring warnings.

[-k]

Keeps the server main stub. buildscaserver generates a main stub with data structures such as the service table and a main() function. This is normally compiled and then removed when the server is built. This option indicates that the source file should be retained.

Note:

To see the source filename, use the -v option.

Caution:

The generated contents of this file may change from release to release. It is advised that you do not depend on the data structures and interfaces exposed in this file. This option is provided to aid in debugging build problems.

[-t]

Not used in current release.

[-S]

Required when the server makes use of C structure input or output buffers and the -w option is specified.

Note:

When the -w option is not specified, buildscaserver uses ATMI binding to determines if structures are used.The -S option is not required.

The buildscaserver -S option does not take an option argument.

Environment Variables

TUXDIR

Finds the SCA libraries and include files to use when compiling the client applications.

CC

Indicates the compiler to use to compile all files with .c or .cpp file extensions. If not defined, the default C++ language compile command is invoked to compile all .c and .cpp files.

CFLAGS

Indicates any arguments that are passed as part of the compiler command line for any files with a .c or .cpp file extensions. If CFLAGS does not exist in the buildscaserver command environment, the buildscaserver command checks for the CPPFLAGS environment variable.

Note:

Arguments passed by the CFLAGS environment variable take priority over the CPPFLAGS variable.

CPPFLAGS

Contains a set of arguments that are passed as part of the compiler command line for any files with a .c or .cpp file extensions.

This is in addition to the command line option "-I$(TUXDIR)/include" for UNIX systems or the command line option /I%TUXDIR%\include for Windows systems, which is passed automatically by the buildscaserver command. If CPPFLAGS does not exist in the buildscaserver command environment, no compiler commands are added.

LD_LIBRARY_PATH (UNIX systems)

Indicates the directories that contain shared objects to be used by the compiler, in addition to the objects shared by the CORBA software. A colon (:) is used to separate the list of directories. Some UNIX systems require different environment variables:

•	HP-UX systems use SHLIB_PATH

•	AIX systems use LIBPATH

LIB (Windows only)

Indicates a list of directories where libraries are available. A semicolon (;) is used to separate the list of directories.

Portability

This utility can be used on any platform that supports the Oracle Tuxedo environment.

Example(s)

buildscaserver -c uBike.server -o uBikeSCASvr

Error Reporting

This command checks for the following inconsistencies in the SCDL code and reports error messages if:

•	at least one syntax error in the SCDL files

•	none of the composites contain any service with an ATMI binding

•	at least one composite contains services defining ATMI bindings with incompatible <remoteAccess> elements. <remoteAccess> elements with a value of WorkStation are not supported by this command.

•	/binding.atmi/@requires contains a legacy value and /binding.atmi/map elements contain values that conflict (for example, the same Tuxedo service name mapped to two or more different methods)

mkfldfromschema, mkfld32fromschema

The mkfldfromschema and mkfld32fromschema commands take an XML schema as input and produce a field table. This table can be processed by the mkfldhdr or mkfldhdr32 command or is loaded by programs that need it. mkfldfromschema is used with 16-bit FML and mlfld32fromschema is used with 32-bit FML.

These commands have the following restrictions:

•	Attributes cannot be specified

•	Restrictions are ignored because their meaning is application-related

Name

mkfldfromschema, mkfld32fromschema – Generates field table from an XML schema

Synopsis

mkfldfromschema [{-i schema|-u schemaurl}] [-b basenumber] ]-o outputfile]

mkfld32fromschema [{-i schema|-u schemaurl}] [-b basenumber] ]-o outputfile]

Description

These commands take an XML schema as input and generate a field table. The XML schema may be specified using either the -i option or the -u option. If neither option is specified, the schema is read from standard input.

Parameters and Options

mkfldfromschema and mkfld32fromschema supports the following options:

-b basenumber

Adds a *base basenumber line to the generated field table.

-i schema

Displays the name of a file containing an XML schema. The -i option cannot be specified in conjunction with the -u option.

-u schemaurl

A URL where the input schema is located. The URL must start with http://. The -u option cannot be specified in conjunction with the -i option.

-o outputfile

The name of a file that will contain the field table. If this option is not specified, the field table will be written to standard output.

Portability

This utility can be used on any platform that supports the Oracle Tuxedo server environment.

See Also

SCAHOST (5)

mkviewfromschema, mkview32fromschema

The mkviewfromschema and mkview32fromschema commands take an XML schema as input and produce a view file. This file can be processed by the viewc or viewc32 command. mkviewfromschema is used with 16-bit views and mkview32fromschema is used with 32-bit views.

Name

mkviewfromschema, mkview32fromschema – Generates view table from an XML schema

Synopsis

mkviewfromschema [{-i schema|-u schemaurl}] [-o outputfile]

mkview32fromschema [{-i schema|-u schemaurl}] [-o outputfile]

Description

These commands take an XML schema as input and generate a view file. The XML schema may be specified using either the -i option or the -u option. If neither option is specified, the schema is read from standard input.

Options

mkviewfromschema, mkview32fromschema supports the following options:

-i schema

The name of a file containing an XML schema. The -i option cannot be specified in conjunction with the -u option.

-u schemaurl

A URL where the input schema is located. The URL must start with http://. The -u option cannot be specified in conjunction with the -i option.

-o outputfile

The name of a file that contains the output view file. If this option is not specified, the field table is written to standard output.

Portability

This utility can be used on any platform that supports the Oracle Tuxedo server environment.

See Also

SCAHOST (5)

SDO for C++ Specification V2.1published December, 2006

scaadmin

Name

scaadmin – SCA server management command interpreter

Synopsis

scaadmin [-v]

Description

Use the scaadmin command to dynamically redeploy SCA composites or display statistics and status of individual services. The TUXCONFIG environment variable is used to determine the location where the Tuxedo configuration file is loaded.

This command has no effect on servers that have not been built using the buildscaserver(1) command.

Options

The scaadmin command supports the following option:

[-v ]

Causes scaadmin to display the Oracle Tuxedo version number, Tuxedo Patch Level. The command exits after print out.

scaadmin must run on an active node.

Commands

default [-m machine] [-g groupename] [-i srvid] ] [-s servername]

Sets the corresponding argument to be the default machine name, groupname, server id, or servername. If the default command is entered with no arguments, the current defaults are printed.

reload [-m machine] [-g groupname] [-i srvid] ] [-s servername]

This command dynamically reloads the SCA components hosted on Tuxedo servers. The -m, -g, -i and -s options can be used to restrict the reloaded servers to any combination of machine, group, server id and server name.

printstats [-m machine] [-g groupname] [-i srvid] [-s servername]

This command displays the list of services hosted by a server and the associated method, number of queries, and status (active, idle). The -m, -g, -i and -s options can be used to restrict the reloaded servers to any combination of machine, group, server id and server name.

verbose (v) [{off | on}]

Produces output in verbose mode. If no option is given, the current setting is toggled and the new setting is printed. The initial setting is set to off.

help (h) [{command | all}]

Prints help messages. If command is specified, the abbreviation, arguments, and description for that command are printed. all causes a description of all commands to be displayed. Omitting all arguments causes the syntax of all commands to be displayed.

echo (e) [{off | on}]

Echoes input command lines when set to on. If no option is given, the current setting is toggled, and the new setting is printed. The initial setting is off.

quit (q)

Terminates the session

Interoperability

The scaadmin command must run on an active node.

Environment Variables

TUXCONFIG

Used to determine the location where the Tuxedo configuration file is loaded.

Portability

This utility can be used on any platform that supports the Oracle Tuxedo environment.

Example(s)

The following command reloads all the composites hosted by the uBikeServer Tuxedo application server, which was built using the buildscaserver(1) command.

scaadmin

> reload -s uBikeServer

The following command displays statistics on the services offered by the uBikerServer Tuxedo application server, which was built using the buildscaserver(1) command.

scaadmin

> printstats -s uBikeServer

Service Method Status Requests

Processed

SEARCHINVENTORY searchInventory A 37

SCAHOST (5)

Name

SCAHOST - Generic server for Python, Ruby, or PHP SCA components.

Synopsis

SCAHOST SRVGRP="identifier" SRVID="number"

CLOPT="[-A] [servopts options]

-- -w -c composite"

Description

SCAHOST is an Oracle Tuxedo system provided server that provides boot-strapping functionality for Python, Ruby, or PHP programs hosted as SCA components.

SCAHOST relies on Oracle Tuxedo Service Metadata Repository information, and therefore requires being defined after the TMMETADATA system process in the UBBCONFIG file.

Python, Ruby, and PHP components can be hosted by a single SCAHOST. It is preferable that the component(s) hosted contain only Python, Ruby, and PHP components (i.e., no C++ components).

Parameters and Options

-w

Specifies that an SCAHOST instance exposes Web services. By default, only ATMI binding services are exposed. Webs services and ATMI bindings cannot be hosted by the same SCAHOST server, if a composite has services exposed with both bindings, two SCAHOST instances must be configured in order to expose all ATMI and Web Services bindings.

-c composite

Specifies the name of the component that this server will host.

Portability

This command is available on any platform on which the Oracle Tuxedo server environment is supported.

Example(s)

Listing 4‑1 provides an SCAHOST example.

Listing 4‑1 SCAHOST Example

*SERVERS

SCAHOST SRVGRP=GROUP1 SRVID=100

CLOPT="-A -- -c Account"

SCAHOST SRVGRP=GROUP2 SRVID=100

CLOPT="-A -- -c Loan"

 

scapasswordtool

Name

scapasswordtool – Manages passwords for Tuxedo authentication in SCA clients.

Synopsis

scapasswordstore -i passwordidentifier -[a|d]

Description

This command manages the password.store file used by SCA components to refer to Tuxedo-based services.

Passwords are prompted and encrypted. The encrypted version is stored in this file, associated with a clear-text identifier. This command is also used to delete identifier/password pairs from the file.

The password is limited to 40 characters. If standard input is not a terminal, that is, if the user cannot be prompted for a password (as with a Here file, for example), then the APP_PW environment variable is accessed to set the password. If the APP_PW environment variable is not set and standard input is not a terminal, then scapasswordtool prints an error message and exits.

A password.store file is created in the current directory if it does not previously exist.

Parameters and Options

-i passwordidentifier

Required. The identifier specified in the <binding> element. SCA components search the password for this element.

-[a|d]

The -a option adds an identifier/password pair, whereas the -d option deletes it. An error message is printed out and the command processing is aborted in one of the following situations:

•	If -a is used to add an already existing identifier

•	If -d is used to delete a non-existing identifier

Portability

This utility can be used on any platform that supports the Oracle Tuxedo environment.

See Also

setSCAPasswordCallback(3c)

scastructc32, scastructc(1)

Name

scastructc32, scastructc - Structure description compiler for Oracle Tuxedo.

Synopsis

scastructc32 [-n] [-d viewdir] structfile [structfile . . . ]
scastructc [-n] [-d viewdir] structfile [structfile . . . ]

Description

scastructc32 and scastructc are a Oracle Tuxedo SCA structure description compiler programs. These commands take a source structure description file and produces:

•	A binary file, which is interpreted at run time to effect the actual mapping of data between FML buffers and C++ structures.

•	One or more header files.

Note:

COBOL is not supported in the SCA environment, therefore scastructc32 and scastructc do not have options to generate COBOL copyfiles.

SCA structure description files are identical to Oracle Tuxedo viewfiles, with the exception that SCA structure description files allow the following extensions:

•	Nested structures are supported. A nested structure may be specified by using the struct keyword in column 1. When this keyword is used, the "cname" value in column 2 must be the name of a previously defined view that describes a nested structure.

The value in column 3 will be interpreted as the name of the element for the inner structure within the outer structure. If the value in column 3 is "-", then the name of the inner structure element will be the same as the name of the inner structure.

As with other types, the value in column 4 can be used to specify a count of the number of times the inner structure is included in the outer structure. The "flag" and "size" values in columns 5 and 6 are not used for struct elements.

scastructc32 is used for 32-bit FML. It uses the FIELDTBLS32 and FLDTBLDIR32 environment variables. scastructc is used for 16-bit FML. It uses the FIELDTBLS and FLDTBLDIR environment variables.

If none of the SCA structure file extensions are used, then binary files produced by scastructc32 are compatible with binary files produced by viewc32 and binary files produced by scastructc are compatible with binary files produced by viewc.

The structfile is a file containing source structure descriptions. More than one structfile can be specified on the scastructc32 or scastructc command line as long as the same VIEW name is not used in more than one structfile.

By default, all views in the structfile are compiled and two or more files are created: a view object file (with a .V suffix) and a C header file (with a .h suffix). The name of the object file is structfile.V in the current directory unless an alternate directory is specified through the -d option. C header files are created in the current directory.

Note:

scastructc32 and scastructc generate a binary file with suffix .V on Unix and suffix .VV on Windows.

At scastructc32 or scastructc compile time, the compiler matches each field id and field name specified in the viewfile with information obtained from the field table file, and stores mapping information in an object file for later use. Therefore, it is essential to set and export the environment variables FIELDTBLS and FLDTBLDIR to point to the related field table file. For more information, see Programming an Oracle Tuxedo ATMI Application Using FML and Programming an Oracle Tuxedo ATMI Application Using C.

If the scastructc32 or scastructc compiler cannot match a field name with its field id because either the environment variables are not set properly or the field table file does not contain the field name, a warning message, Field not found, is displayed.

With the -n option, it is possible to create a view description file for a C structure that is not mapped to an FML buffer. Programming an Oracle Tuxedo ATMI Application Using C discusses how to create and use such an independent view description file.

Parameters and Options

The following options are interpreted by scastructc32 and scastructc:

-n

Used when compiling a structure description file for a C structure that does not map to an FML buffer. It informs the structure compiler not to look for FML information.

-d viewdir

Used to specify that the structure object file is to be created in a directory other than the current directory.

Note:

On Windows, the following additional options are recognized:

-c { m | b }

Specifies the C compilation system to be used. The supported value for this option is m for the Microsoft C compiler. The Microsoft C compiler is the default for this option. The -c option is supported for Windows only.

-1 filename

Specifies that pass 1 should be run, and the resulting batch file called filename.bat should be created. After this file is created, it, should be executed before running

pass 2. Using pass 1 and pass 2 increases the size of the views that can be compiled. The -1 option is supported for Windows only.

-2 filename

Specifies that pass 2 should be run to complete processing, using the output from pass 1. The -2 option is supported for Windows only.

Portability

The output view file is a binary file that is machine and compiler-dependent. It is not possible to generate a view on one machine with a specific compiler and use that view file on another machine type or with a compiler that generates structure offsets differently (for example, with different padding or packing).

See Also

scastructdis32, scastructdis

Programming an Oracle Tuxedo ATMI Application Using FML

Introduction to FML Functions in Oracle Tuxedo ATMI FML Function Reference

Programming an Oracle Tuxedo ATMI Application Using C

scastructdis32, scastructdis

Name

scastructdis32, scastructdis - Disassembler for binary structure files and viewfiles.

Synopsis

scastructdis32 [-E envlabel] viewobjfile [viewobjfile...]
scastructdis [-E envlabel] viewobjfile [viewobjfile...]

Description

scastructdis32 disassembles a view object file produced by scastructc32 or viewc32 and displays view information in viewfile format. In addition, it displays the offsets of structure members in the associated structure.

One or more viewobjfiles (with a .V suffix) can be specified on the command line. By default, the viewobjfile in the current directory is disassembled. If this is not found, an error message is displayed.

Because the information in the viewobjfile was obtained from a match of each field id and field name in the viewfile with information in the field table file, it is important to set and export the environment variables FIELDTBLS32 and FLDTBLDIR32.

The scastructdis32 output looks the same as the original structure description(s), and is mainly used to verify the accuracy of the compiled object structure descriptions.

scastructdis is used for files originally compiled with scastructc or viewc. It uses the FIELDTBLS and FLDTBLDIR environment variables instead of FIELDTBLS32 and FLDTBLDIR32.

See Also

pass 2. Using pass 1 and pass 2 increases the size of the views that can be compiled. The -1 option is supported for Windows only.

Programming an Oracle Tuxedo ATMI Application Using FML

scatuxgen(1)

Name

scatuxgen - Generates Tuxedo Service Metadata Repository interface information from an SCA interface.

Synopsis

scatuxgen (-c <composite file name> | -i <interface file name> [-I <inbuf>] [-O <outbuf>])-s <service name> [-t <string-type>][-w [-n <namespace> -a <network address>]] [-v]

Description

Generates Tuxedo Service Metadata Repository interface information based on SCA abstract class definitions. Service Metadata generation is performed by parsing a composite file (in SCDL) which allows locating the interface referenced by the <service name> value, or directly by specifying the interface to process at the command line.

The interface is an SCA-compliant abstract class definition contained in a C++ header file. Parsing the composite file allows you to take advantage of binding.atmi details (for example, buffer types and xsd schemas) when available.

When binding.atmi information is not available, scatuxgen can directly process a C++ interface directly by giving the name of the header file containing it as an argument to the command line.

The generated file name is composed using the service name, input using the command-line option, and the .mif file, and possibly the.wsdf extension.

Options

-c composite file name

Specifies the pathname of the composite file to be processed. This path is relative to where the command is run.

-i interface file name

Specifies the name of the interface file to be processed. This path is relative to where the command is run.

-I inbuf

Specifies the type of input Tuxedo buffer to generate in the service metadata entry. This option is only valid when used in conjunction with the -i and -w options . Acceptable values are STRING, CARRAY, X_OCTET, VIEW/<viewname>, X_C_TYPE /<viewname>, X_COMMON/<viewname>, VIEW32/<viewname>, FML, FML32, MBSTRING and XML.

-O outbuf

Specifies the type of output Tuxedo buffer to generate in the service metadata entry. This option is only valid when used in conjunction with option -i. Acceptable values are STRING, CARRAY, X_OCTET, VIEW/<viewname>, X_C_TYPE/<viewname>, X_COMMON/<viewname>, VIEW32/<viewname>, FML, FML32, MBSTRING and XML.

-E outbuf

Specifies the type of error Tuxedo buffer to generate in the service metadata entry. This option is only valid when used in conjunction with option -i. Acceptable values are STRING, CARRAY, X_OCTET, VIEW/<viewname>, X_C_TYPE/<viewname>, X_COMMON/<viewname>, VIEW32/<viewname>, FML, FML32, MBSTRING and XML.

-s service name

Specifies the name of the service to be generated when using an interface file. It also specifies the base of the output file(s).

-t string-type

Specifies that scatuxgen should map xsd:string types in XML schemas to Tuxedo mbstring (FLD_MBSTRING).

-w

Specifies scatuxgen produces a WSDF document.

-n

When producing a WSDF document, can be used to indicate the Definition/@wsdlNameSpace attribute value. If not specified, the Definition/@wsdlNamespace attribute contains the '##NAMESPACE##' placeholder.

-a

When producing a WSDF document, can be used to indicate the Definition/WSBinding/AccessingPoints/Endpoint/@address attribute value. If not specified, the Definition/WSBinding/AccessingPoints/Endpoint/@address attribute will contain the '##ADDRESS##' placeholder.

-v

Specifies scatuxgen in verbose mode.

Portability

This utility can be used on any platform that supports the Oracle Tuxedo environment.

Example

The following example results in a TOUPPER.mif file created in the same directory where scatuxgen is invoked:

$ scatuxgen -c simpapp.composite -s TOUPPER

See Also

Flat File view. If this option is specified, then all the generated files are put in the target root directory. The default is Tree File view.

setSCAPasswordCallback(3c)

Name

setSCAPasswordCallback() – Sets the callback for retrieving a password associated with an identifier in a <binding.atmi> element.

Synopsis

#include <tuxsca.h>
void setSCAPasswordCallback(char * (_TMDLLENTRY *)(*disp) (char
*identifier))

Description

setSCAPasswordCallback() allows an SCA component to identify the callback that returns the clear-text password that is passed to the appropriate authentication code.

The function pointer passed on the call to setSCAPasswordCallback() must conform to the specified parameter definition. The _TMDLLENTRY macro is required for Windows-based operating systems to obtain the proper calling conventions between the Tuxedo libraries and your code. On UNIX systems, the _TMDLLENTRY macro is not required because it expands to the null string.

The identifier points to the password identifier passed to the callback function. The callback function then returns a char * that points to the actual clear-text password.

Return Values

The setSCAPasswordCallback() function does not return any data.

Errors

On failure, setSCAPasswordCallback() sets tperrno to one of the following values:

[TPEPROTO]

setSCAPasswordCallback() has been called in an improper context.

[TPESYSTEM]

An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

See Also

scapasswordtool

tuxscagen(1)

Name

tuxscagen – Generates SCA, SCDL, and server-side interface files for Tuxedo services.

Synopsis

tuxscagen [-s <target-root-directory>] [-d <service-name>][-C <TUXEDO_cltname>][-u <TUXEDO_username>][(-S | -j <java_package_name>)][-o <output_SCDL_filename>][-i <output_interface_filename>[-m <max-intf-arguments>][-y] [-v] [-F] [-c] [-h][-g<i|a|s>] [-trepository=<filename> | -tinfile=<metarepos.infile> | -tmetadata]

Description

tuxscagen is used to generate interface and SCDL files. The interface files are used for developing the SCA component using ATMI binding, or wrap existing Tuxedo services in an SCA component. The SCDL files are assembly artifacts that help SCA run time to locate the module and services.

Parameters and Options

tuxscagen supports the following options:

-s target-root-directory

Specifies the location of the root directory where the generated SCDL and interface files are located. The directory must exist and with write access permission; if it does not exist, the tool issues an error message and fails.

-d<service-name>

Specifies the name of Tuxedo service in the Tuxedo Metadata Repository. If this option is not specified, all services in the repository or in the input file are selected.

Abbreviation: there is no abbreviation for this option

-C <TUXEDO_cltname>

The Tuxedo client name. Use cltname as the client name when joining the Tuxedo application.

-u <TUXEDO_username>

The Tuxedo user name. Use username as the user name when joining the Tuxedo application. This is required when Tuxedo security level is higher than APP_PW and input method is to retrieve Tuxedo Service Metadata from TUXEDO.TMMETAREPOS Service.

-j <java_package_name>

This option generates JAVA interface files. By default, tuxscagen generates C++ header files. If -g is not specified but if -j <java_package_name> is specified then -ga is assumed. However, if -g sub-option i or s is specified, a warning message is displayed.

-o <output_SCDL_filename>

This option specifies the output SCDL filenames for single composite and single componentType file. If this option is not specified, then by default, one composite and one componentType are generated for each Tuxedo service. However, if this option is specified with the output filename, only one composite and one componentType file is generated for all the matching Tuxedo services. If the specified <output_SCDL_filename> already exists, an interactive prompt is displayed and requires user input (unless -y is specified). If this option is specified, -F is automatically implied.

-i <output_interface_filename>

This option specifies the output interface filenames for single abstract class header file and single class implementation header file. If this option is not specified, then by default, it generates one abstract interface class header file and one implementation class header file.

However, if this option is specified with output interface filename then only one abstract class header file and one implementation header file is generated for all matching Tuxedo services. If the specified <output_interface_filename> already exists, an interactive prompt is displayed and requires user input (unless -y is specified).

If this option is specified, -F is automatically implied.

-m <max-intf-arguments>

This option specifies the maximum number of arguments allowed in the interface method. If the number of arguments exceeds the specified threshold then a complex data type is used as the input argument for the interface method. The complex data type used is commonj::sdo::DataObjectPtr.

If -m is not specified, the default threshold is 10.

If 0 specified, it will always generate using commonj::sdo::DataObjectPtr.

If -ga is not specified, this option is ignored.

-y

This option suppresses Really overwrite files:<filename> [y, q] ? so that the script can run without user input. This question appears if either or both -o and -i are specified. If both these options are not specified, by default existing files are replaced.

-v

This option turns on the verbose mode.

-h

If this option is specified, online help is printed and all other options are ignored.

-F

Flat File view. If this option is specified, then all the generated files are put in the target root directory. The default is Tree File view.

-c

Generates client-side SCDL. By default tuxscagen generates server-side SCDL, specifying this option changes it to generate client-side SCDL.

-g a|i|s

This option is used to specify the files to generate. The sub-options can be combined. The a sub-option is used to generate abstract base class header files. The sub-option i is to generate implementation class header files. Sub-option s is used to generate SCDL files. To generate both header files, specify -gai. To generate all files, specify -gais.

If not specified, -gais is assumed.

[-trepository=<filename> | -tinfile=<metarepos.infile> | -tmetadata]

This option specifies the processing type.

If -trepository=<filename> is specified, tuxscagen retrieves service parameter information from the Service Metadata repository file <filename>.If -tinfile=<metarepos.infile> is specified, then tuxscagen retrieves service parameter information from <metarepos.infile>, where the <metarepos.infile> syntax is suitable for input to tmloadrepos. If -tmetadata is specified, tuxscagen retrieves service parameter information from the Tuxedo TMMETADATA server.

At most, one -t option can be specified; the default is -tmetadata.

[-S]

Specifies tuxscagen generate a structures for any function parameter or return value that would otherwise have been passed using DataObjectPtr.

When the -S option is used, a structure definition is generated as part of the generated abstract class header file ${TUXSERVICE}.h. tuxscagen -S also generates a Tuxedo view file ${TUXSERVICE}.v describing the generated view(s).

If tuxscagen input does not specify a maximum number of occurrences for a field, then tuxscagen -S generates 1 occurrence for that field. If tuxscagen input specifies an unlimited number of occurrences for a field, then tuxscagen -S generates an error.

If tuxscagen input does not specify a maximum length for a string, carray, or mbstring parameter, then tuxscagen generates a maximum length of 80 characters plus trailing NULL for that parameter and outputs a warning message to check if this is sufficient.

Note:

The use of an 80 character default is different from viewc. An unspecified length in viewc causes a length of 1 character plus trailing null to be generated, which is insufficient for most applications.

The tuxscagen -S option will not change the underlying Tuxedo transport type specified for the <inputBufferType>, <outputBufferType>, and <errorBufferType> elements in the generated composite file. When data is passed via DataObjectPtr or via a structure, this will normally be FML32.

Note:

Structures are not supported for the SCA Java interface. Using tuxscagen with both the -j and -S options results in an error.

Portability

This utility can be used on any platform that supports the Oracle Tuxedo environment.

Example

The following command is used to generate SCDL, interface, and implementation header files from a Tuxedo Metadata Repository file named myrepository in the current working directory. The number of interface method input arguments is limited to 8. If the limit is exceeded, the XSD schema file is still generated.

tuxscagen -s /home/tux/sca -Dname=TRANSFER -gais -m 8 -trepository=myrepository

See Also

scatuxgen(1),tmloadrepos(1), tmunloadrepos(1)

Managing The Tuxedo Service Metadata Repository in Setting up an Oracle Tuxedo Application