Key Concepts

This page describes de key concepts you should know before using the API's.

Description:

The API's have been designed so that you have a minimum number of parameters to pass. They use the concept of the "current object", where Object can refer to a label, dataset, chart, etc. In other words, when adding data to a chart, you do not have to tell the API which chart you are adding it to, it will automatically add it to the "current" chart. Similarly, when telling the API to render a chart, you do not have to tell it which chart, it will also automatically render the "current" chart. Or, when you create a label for your chart, the label just created will become the 'current' label and when you call other API routines to set the font, color or other attributes, it will automatically apply to that label. If you are working with more than one chart at a time, you can name each chart as you initialize it, and use an API to switch the current chart to one of the named charts. You can also name datasets, shapes and other objects. Normally you only need to do this if you are working with more than one of these at a time; otherwise, leaving the name blank will suffice.

The API's may have one or more required parameters and one or more optional parameters. If you fail to PASS a required parameter, the API will CANCEL with an error message indicating which parameter is missing. When PASSing optional parameters, you may have to PASS dummy parameters to fill in any gaps. For example, if an API takes 3 optional parameters, and you want to PASS a value to the second parameter, then you will have to PASS something for the first optional parameter, then the value you want for the second parameter. Otherwise, the API will associate your value with the first optional parameter, not the second.

The parameters for the API's are case insensitive, so TOPLEFT is the same as tOpLeFt or tOPLEFt.

For every API, there is a work field of the same name that will contain any return codes from the API. You can test this work field for a non blank value after returning to see if an error occurred. The work fields are tokenized, so you can SCAN the possible values in the ILF editor.

The API names begin with a period to distinguish the external routines from the internal ones. You will notice a number of other subroutines in the 0CD application that do not begin with a period. These are the internal subroutines used by the API itself, do not try to call them directly.

The 1CD application contains a number of examples. Use it as a reference until you are familiar with using the API's. The examples come directly from the samples in the Chart Director documentation.

Finally, the code examples given in the wiki are designed to be copied and pasted into your own process. You should be able to select the example code, copy it to the clipboard and then paste it into the ILF editor. Although the examples use a GOSUB command to call the API, you might want to consider using a SUBR with SUBPROCESS invocation instead. This will greatly reduce the size of the executable module and the time it takes to create the Em. There is a slight performance trade off, but unless you are generating several charts at a time, it won't be noticed.

Comments

Read what other users have said about this page or add your own comments.

-- JeanNeron - 2011-09-15