The Method Definition Utility (MDU) can be used to add, change, and delete data in the Synergy Method Catalog. The utility displays a list of all methods in the SMC and has two main data input screens: one for entering information about the method and one for entering information about each parameter. The MDU includes a search function for both methods and parameters, as well as options to import and export data (see Importing and exporting methods) and to verify repository structure sizes (see Verifying repository structure sizes and enumerations).
On Windows, you can start the MDU from Workbench or—on 32-bit platforms—by double-clicking on mdu.dbr from Windows Explorer. On all platforms, you can start the MDU using the command line syntax; see Method Definition Utility.
This topic includes the following:
Modifying methods and parameters
Searching for methods and parameters
Creating new methods
|
Data about your Synergy routines must be entered correctly in the SMC! In addition, the SMC must remain in sync with your Synergy code. If you change your code (e.g., change the data type of a function return value, add a new parameter, or alter a structure size in the repository), don’t forget to update the SMC. (You can quickly update structure size changes with the Verify Catalog utility; see Verifying repository structure sizes and enumerations.) |
| 1. | Start the Method Definition Utility. See Method Definition Utility for the command line syntax. |
When the MDU opens, the methods list (see figure 1) displays the methods already in the catalog. The SMC is preloaded with several methods: XFPL_LOG, XFPL_REGCLEANUP, and a number of methods needed to run the xfNetLink and xfServerPlus test programs. (The methods for the test programs are in the interface xfTest.)
|
By default, the methods list displays the method name. You can toggle between displaying the method name and the method ID, by pressing Ctrl+V or selecting Functions > Toggle View.
Data displayed on the methods list can be sorted by interface name (the default), method name (or method ID, depending on the toggle view setting), routine name, or ELB/shared image name. To change the sort order, click on the column headings (Windows only) or use the options on the Sort menu.
| 2. | To add a new method do one of the following: |
- Click the Add button.
- Press the Insert key.
- Select Functions > Add Method.
The Method Definition window will display (see figure 2).
| 3. | Specify the following information in the Method Definition window. |
|
|
Method name
Enter a name for the method. The method name must be unique for the interface in which it is included. (This comparison is case insensitive.) Valid values for this field are alphanumeric characters and the underscore character ( _ ). The method name must begin with an alpha character. The maximum length is 50 characters.
When you exit the Method name field, the MDU copies the value you entered to the Method ID field. If the method name is longer than 31 characters (which is the maximum length for method ID), it will be truncated. If the MDU cannot create a valid and unique method ID from the method name, it will prompt you to supply a method ID. See Specifying a method ID for instructions on specifying or changing the method ID.
See Understanding routine name, method name, and method ID for details on the role of the method name and how it differs from method ID.
(optional) If this method is going to be included in a Java JAR file or a .NET assembly, enter the name of the interface that this method is part of. Valid values for this field are alphanumeric characters and the underscore character ( _ ). The interface name must begin with an alpha character. This field is case sensitive.
Methods are grouped into interfaces for inclusion in a Synergy component. The interface name will be used to select interfaces to include in the component, and users will see it as the class name when they use your JAR file or assembly.
|
Although the Interface name field is case sensitive, we do not recommend creating interface names that differ only in case. If you attempt to generate a component that contains two or more interfaces that differ only in case, the genjava or gencs utility will append a number (starting with 1 and incrementing) to the end of each of the additional interfaces to make the class names unique (e.g., MYINTFACE, MyIntFace1, myintface2, etc.). You will also see numbers appended to class names when there is a structure name that is the same as an interface name. Because structure classes are processed first, it is the procedural class name that will be altered. If you are using xfNetLink .NET, the interface name must be different than the method name. Matching interface and method names will result in a “member names cannot be the same as their enclosing type” error when the classes are compiled. |
(optional) Enter a description of the method. If you are using a Java or .NET client, the information in this field will be included in the generated code as a documentation comment and, subsequently, in your generated Javadoc or API documentation, should you choose to create it. (See Generating Javadoc or Generating API documentation for more information on generating documentation.) If you are using a Synergy client, this field is ignored.
The Method desc field will hold six lines of 50 characters each. Only the first line can be edited on the Method Definition window. To access all six lines, press F9 or select Functions > Edit Description while your cursor is in this field. (On Windows, you can also click the drilldown button.) The Description dialog box will display. Text in this dialog box word-wraps automatically. Pressing Enter will move the cursor to the next line, resulting in a line break that will be preserved in the generated code. Special characters (e.g., < and >) will be handled by genxml, genjava, and gencs, so you should enter these characters as you want them to appear in the Javadoc or API documentation. When you have completed the description text, select OK or press F3 in the Description dialog box to save the text and return to the Method Definition window.
Routine name
Enter the name of the Synergy subroutine or function. Valid values are alphanumeric characters, the underscore character ( _ ), and the dollar sign ($). The routine name must begin with an alpha character
ELB name
Enter the name of the ELB or shared image in which the Synergy routine is stored. Include the full path or logical; don’t include the .elb or .exe file extension.
On Unix and OpenVMS, if the ELB or shared image name is longer than 51 characters, press F10 or select Functions > Edit ELB Name while your cursor is in this field to display the ELB Name dialog box. Enter the complete ELB or shared image name and press F3 or select Main > Exit to save changes and return to the Method Definition window.
|
|
If you use logicals in the ELB name field, you must define them in the xfpl.ini file (SERVER_INIT.COM on OpenVMS) so that xfServerPlus knows how to resolve them. See Defining logicals. |
Return type
If you are defining a function, select the Synergy DBL data type of the returned data. For subroutines, select “No return value”. System.String and Enumerations are supported only on Java and .NET clients; all other return types are supported on all clients.
If you select Enumeration, a list of enumerations defined in the current repository will display. Select an enumeration from the list by highlighting it and pressing Enter (on Windows, you can also double-click).
|
While the list of enumerations is displayed, you can select Functions > Find to locate an enumeration in the list. |
The MDU will display the enumeration name in a read-only field below the return type.
|
|
To check the location of the current repository, select Main > Repository Location. If the fields are blank, the MDU was unable to locate a repository on start-up. To change the repository, you must restart the MDU. |
Length
If you specified a return type, enter the size of the return value. Note the following:
- For decimal return values coerced to DateTime or nullable DateTime data types, the length is determined by the selected DateTime format.
- For System.String data types, this field is set to blank.
- For Enumeration data types, this field is set to 4.
Precision
If you specified that the return type is implied-decimal, enter the precision. For example, if the return value is a d6.2, enter 6 in the Length field and 2 in the Precision field.
If the return type is decimal, implied-decimal, or integer, you can optionally select a non-default data type for the return value to be coerced to on the client side. Supported on Java and .NET clients only. On Java, a DateTime coerced type is mapped to the Calendar class and decimal is mapped to BigDecimal; nullable types are not supported on Java. Select “Default” to use default type mapping. See Appendix B: Data Type Mapping for xfNetLink Java and Appendix C: Data Type Mapping for xfNetLink .NET for more information on data type mapping and coercion.
Format
If the coerced type is DateTime or nullable DateTime, select the desired format.
Return desc
(optional) Enter a description of the return value. If you are using a Java or .NET client, the information in this field will be included in the generated code as a documentation comment and, subsequently, in your generated Javadoc or API documentation, should you choose to create it. If you are using a Synergy client, this field is ignored. See the description of Method desc for details on creating a multi-line description.
Enable encryption
Select this check box to ensure that this method requires encryption. Starting with version 11.1, xfServerPlus supports only master encryption; consequently, selecting this field is optional, but it acts as a fail-safe. If the method is marked for encryption in the SMC but encryption is not enabled on the server, the error “Method requires encryption” is generated. See Ensuring that specific methods are encrypted for more information.
| 4. | Select OK or press F3 to save your work. |
| 5. | If this is a new method, you will be prompted to define parameters. If there are no parameters for this method, select No at the prompt. If there are parameters, select Yes and see Defining parameters for instructions. |
Specifying a method ID
When you enter a method name on the Method Definition window, the MDU copies that value to the Method ID field, which is a display-only field on the Method Definition window. You can edit or change the method ID by accessing the Method ID dialog box.
|
|
The method ID must be unique. If the MDU cannot create a valid and unique method ID by copying the value in the Method name field, it will prompt you to supply your own method ID and display the Method ID dialog box. |
| 1. | When the Method Definition window is displayed, select the Method ID button, or press F8, or select Functions > Method ID to display the Method ID dialog box. |
| 2. | Enter a method ID. This field is case sensitive. The method ID must be unique for the method catalog. Valid values for this field are alphanumeric characters and the underscore character ( _ ). The method ID must begin with an alpha character. |
| 3. | Select OK or press F3 in the Method ID dialog box to save changes and return to the Method Definition window. |
Defining parameters
Follow these instructions to define parameters for a new method or add parameters to an existing method. A method can have a maximum of 253 parameters. You should define parameters in the order in which they are passed; the MDU assigns a sequence number to each parameter as you define it. See To resequence parameters for instructions on changing the sequence.
The first time you define parameters for a method, the Parameter Definition window displays in creation mode, as shown in figure 3. When this window is in creation mode, each time you select the Next button (or press Ctrl+N or select Functions > Next Parameter), the data you entered will be saved and the window refreshed so that you can enter another parameter. When you have entered all parameters for the method, select Done.
If you are adding parameters to a method that already has parameters, the Parameters list window displays the currently defined parameters. Highlight the line above where you want the new parameter to be added, and then click the Add button, press the Insert key, or select Functions > Add to display the Parameter Definition window in modify mode. When the window is in modify mode, selecting OK will save the parameter data and return you to the Parameters list window.
|
|
It is crucial that you define parameters correctly in the SMC! When making a call, xfServerPlus checks what you send in the call against what you defined in the SMC. If there are discrepancies, xfServerPlus will signal a nonfatal error. xfServerPlus cannot check what you send against what the Synergy routine requires, nor can it check what is defined in the SMC against the Synergy routine. If you define parameters incorrectly in the SMC and send data as it is defined, the error will not be detected until the routine is called on the server, and the result may be a fatal error. |
| 1. | Complete the fields in the Parameter Definition window. |
|
|
Parameter name
Enter an identifying name for the parameter.
Valid values for this field are alphanumeric characters and the underscore character ( _ ). The parameter name must begin with an alpha character and must be unique for the method. (This comparison is case sensitive.) You may want to use the name of the Synergy argument as the parameter name.
- If the parameter you are defining is a structure (supported on Java and .NET clients only), press F7 or select Functions > Select Structure to display a list of structures in the current repository. Select a structure from the list by highlighting it and pressing Enter (on Windows, you can also double-click).
The MDU will enter the structure name as the parameter name and display the structure name in a read-only field below the data type. You can change the parameter name if desired. (If you enter a parameter name before displaying the list of structures, it will not be overwritten with the structure name.) The MDU also fills in the data type and the length with information from the repository.
|
|
You can also display the list of structures in the current repository by selecting “Structure” from the Data type selection list. While the list of structures is displayed, you can select Functions > Find to locate a structure in the list. |
- If the parameter you are defining is an enumeration (supported on Java and .NET clients only), press F6 or select Functions > Select Enumeration to display a list of enumerations in the current repository. Select an enumeration from the list by highlighting it and pressing Enter (on Windows, you can also double-click).
The MDU will enter the enumeration name as the parameter name and display the enumeration name in a read-only field below the data type. You can change the parameter name if desired. (If you enter a parameter name before displaying the list of enumerations, it will not be overwritten with the enumeration name.) The MDU fills in the data type and the length with information from the repository.
|
|
You can also display the list of enumerations in the current repository by selecting “Enumeration” from the Data type selection list. While the list of enumerations is displayed, you can select Functions > Find to locate an enumeration in the list. |
|
|
To check the location of the current repository, select Main > Repository Location. If the fields are blank, the MDU was unable to locate a repository on start-up. To change the repository, you must restart the MDU. |
Description
(optional) Enter a description of the parameter. If you are using a Java or .NET client, the information in this field will be included in the generated code as a documentation comment and, subsequently, in your generated Javadoc or API documentation, should you choose to create it. (See Generating Javadoc or Generating API documentation for more information on generating documentation.) If you are using a Synergy client, this field is ignored.
This field will hold six lines of 50 characters each. Only the first line can be edited on the Parameter Definition window. To access the additional lines, press F9 or select Functions > Edit Description while your cursor is in this field. (On Windows, you can also click the drilldown button.) The Description dialog box will display. Text in this dialog box word-wraps automatically. Pressing Enter will move the cursor to the next line, resulting in a line break that will be preserved in the generated code. Special characters (e.g., < and >) will be handled by genxml, genjava, and gencs during code generation, so you should enter these characters as you want them to appear in the Javadoc or API documentation. When you have completed the description text, select OK or press F3 in the Description dialog box to save the text and return to the Parameter Definition window.
Select the Synergy DBL data type of the parameter. If you selected a structure or enumeration while you were in the Parameter name field, the MDU sets this field to the correct data type. Not all parameter types are supported on all clients; see the table below.
For information on when to specify a parameter type of Handle, see Passing a single parameter as a memory handle and Returning a collection of structures.
To pass binary data (such as a JPEG file or Synergy RFA), select “Binary (handle)”. See Passing binary data for more information.
Length
Enter the size of the parameter. Note the following:
- For structures and enumerations, the Length field is completed automatically with information from the repository.
- For arrays and ArrayLists that are not made up of structure elements, enter the element length, not the total array size.
- For decimal parameters coerced to DateTime or nullable DateTime data types, the length is determined by the selected DateTime format.
- For handle, binary (handle), and System.String parameters, this field is blank.
Precision
If the data type is implied-decimal, enter the precision. For example, for a d10.3 parameter, enter 10 in the Length field and 3 in the Precision field.
Coerced type
If the data type is decimal, implied-decimal, or integer, you can optionally select a non-default data type for the parameter to be coerced to on the client side. Supported on Java and .NET clients only. On Java, a DateTime coerced type is mapped to the Calendar class and decimal is mapped to BigDecimal; nullable types are not supported on Java. Select “Default” to use the default type mapping. See Appendix B: Data Type Mapping for xfNetLink Java and Appendix C: Data Type Mapping for xfNetLink .NET for more information on data type mapping and coercion.
Format
If the coerced type is DateTime or nullable DateTime, select the desired format.
Array
If the parameter is an array, select this field. The parameter must be defined as a real array in your Synergy code; if you use pseudo arrays, you should convert them to real arrays. Arrays are supported for all data types except handle, binary (handle), System.String, and enumeration.
xfNetLink Synergy supports multidimensional arrays (up to 9 dimensions); the number of dimensions and elements per dimension are calculated from theH data passed. xfNetLink Java and xfNetLink .NET support only one-dimensional arrays. The total size of an array passed to the Synergy server may be greater than 64K, but each element in the array must be less than 64K. See Passing arrays larger than 64K for more information.
ArrayList
If the parameter is a Synergy System.Collections.ArrayList class, select this field. Supported on Java and .NET clients only. ArrayLists are supported for all data types except handle, binary (handle), and enumeration. When using an ArrayList, Data passed can be set to In or Out, but not In/Out. See Passing a System.Collections.ArrayList parameter for more information.
If the parameter is a structure, indicate if you want to pass it as a structure collection. A structure collection is a memory handle on the xfServerPlus side and an ArrayList on the client side. Supported on Java and .NET clients only. When you select this option, Data passed is set to Out, as structure collection parameters can be used only to pass data from Synergy to the client. See Returning a collection of structures for more information.
DataTable
If the parameter is a structure and you selected ArrayList or Structure collection, indicate if you want the parameter to be created as a DataTable on the client. Supported on .NET clients only. See Using DataTables for more information.
Data passed
Indicate if the parameter is passed in, out, or both in and out.
- In indicates this parameter is used to pass data from the client to xfServerPlus. Select In when the parameter is sending input that is not changed by the Synergy routine. This is the default.
- Out indicates this parameter is used to pass data from xfServerPlus to the client. Select Out when the parameter is used to return output information created by the Synergy routine to the client.
- In/Out indicates that this parameter is used to pass data from the client to xfServerPlus and to return an updated version of that data to the client. Select In/Out when the parameter is sent as input, updated by the Synergy routine, and then returned to the client.
Pass by
Indicate if the parameter is passed by descriptor (i.e., normally), value (^VAL), or reference (^REF). The default is Descriptor. If the data type is handle or binary (handle), the MDU sets this field to Descriptor.
Required
If the parameter is required, select this field. The default is Required. If the parameter is optional, clear this field.
Optional parameters are not supported in xfNetLink Java and xfNetLink .NET. When genjava or gencs is run, any parameters marked as optional will be converted to required and a warning message will be generated. (This is because these languages do not support optional parameters.)
If you are finished adding parameters, select the Done button (or F3 or Functions > Done). The Parameters list window will display, with the new parameter(s) added to the list.
| 3. | If the window is in modify mode, select OK or press F3. The Parameters list window will display, with the new parameter added to the list. |
| 4. | Select Done or press F3 in the Parameters list window. The MDU calculates the total number of parameters and the number of required parameters and updates the count on the Method Definition window. |
| 5. | Select OK or press F3 in the Method Definition window. |
The numbers on the left side of the Parameters list window reflect the order in which the parameters are passed when this routine is called. New parameters are inserted below the parameter that is highlighted when you select Add. (The parameter sequence number also appears on the Parameter Definition window below the method name or method ID.)
To resequence parameters, highlight the parameter you want to move and do one of the following to move it to the correct location:
- Use the Move up and Move dn buttons in the Parameters list window.
- Press Ctrl+U to move it up or Ctrl+D to move it down.
- Use the Move Up and Move Down commands on the Functions menu.
Modifying methods and parameters
To modify methods
Use this procedure to change any data on the Method Definition window or on the dialog boxes accessed from that window, such as the Method ID dialog box and the Description dialog boxes.
|
|
The Date Last Updated field in the upper right corner of the Method Definition window reflects the date that this record was last changed. It is updated automatically when you change and save the record. |
| 1. | In the methods list, highlight the method you want to change. |
| 2. | Select it by clicking the Modify button, pressing Enter, or selecting Functions > Modify Method. |
| 3. | Modify the method data as needed. See Creating new methods for details on completing the fields. For information on changing the method ID, see Specifying a method ID. |
| 4. | Select OK or press F3 to exit and save your changes. |
To modify parameters
| 1. | In the methods list, highlight the method that the parameter is associated with and then click the Modify button, press Enter, or select Functions > Modify Method. |
| 2. | On the Method Definition window, select the Parameter button, press F7, or select Functions > Parameters. |
| 3. | In the Parameters list window, highlight the parameter to change and then click the Modify button, press Enter, or select Functions > Modify. |
| 4. | Modify the parameter data as needed. See Defining parameters for details on completing the fields. |
| 5. | Select OK or press F3 in the Parameter Definition window. |
| 6. | Select Done or press F3 in the Parameters list window. |
| 7. | Select OK or press F3 in the Method Definition window. |
Deleting data from the SMC
To delete an interface
This procedure deletes an interface and all methods associated with it.
| 1. | In the methods list, highlight one of the methods that is in the interface you want to delete. |
| 2. | Select Functions > Delete Interface. |
| 3. | Select Yes at the prompt to confirm the deletion. |
To delete a method
This procedure deletes a method and all parameters associated with it.
| 1. | In the methods list, highlight the method you want to delete. |
| 2. | Click the Delete button, press the Delete key, or select Functions > Delete Method. |
| 3. | Select Yes at the prompt to confirm the deletion. |
To delete a parameter
| 1. | In the methods list, highlight the method that the parameter is associated with and then click the Modify button, press Enter, or select Functions > Modify Method. |
| 2. | On the Method Definition window, select the Parameter button, or press F7, or select Functions > Parameters. |
| 3. | In the Parameters list window, highlight the parameter you want to delete. |
| 4. | Click the Delete button, press the Delete key, or select Functions > Delete. |
| 5. | Select Yes at the prompt to confirm the deletion. |
| 6. | Select Done or press F3 in the Parameters list window. |
| 7. | Select OK or press F3 in the Method Definition window. |
Searching for methods and parameters
There are search functions associated with both the methods list and the Parameters list window.
| 1. | In the methods list or the Parameters list window, click the Find button, press Ctrl+F, or select Functions > Find. |
| 2. | For methods, select the search type. You can search for methods by method name (or method ID, depending on the toggle view setting), interface name, routine name, or ELB/shared image name. You can search for parameters only by parameter name. |
| 3. | Enter the search criteria. You can enter a partial name if desired. |
| 4. | Press Enter. The methods list or Parameters list window redisplays, and the first entry that matches the search criteria is highlighted. (The search is case insensitive.) |
| 5. | To find the next entry matching the search criteria, press Ctrl+N or select Functions > Find Next. |
Setting the catalog location
You can change which SMC the MDU is currently updating without restarting the MDU. This function is available only when the methods list is the active window.
|
|
If you access the Catalog Location dialog box from other windows in the MDU, you can view the location of the current catalog but not change it. |
| 1. | From the methods list select Main > Catalog Location. The Catalog Location dialog box displays the location of the currently selected SMC. |
| 2. | Type in a new path or select Functions > Browse to select the directory. (On Windows, you can also click the drilldown button to browse for a directory.) A remote catalog can be specified with an xfServer file specification (e.g., c:\smcDir\@machineName). |
| 3. | Select OK or press F3. If a catalog does not exist in the directory you specify, you will be prompted to create a new catalog in that location. Assuming that the file DBLDIR:defaultsmc.xml is present, the newly-created catalog will include the default methods. |
