Micro Focus Visual COBOL Azure AddPack

The Visual COBOL Azure AddPack enables you to create, build, debug, run and package COBOL applications for Windows Azure.

  • Introduction to COBOL on Azure
  • Azure Prerequisites and Levels of Support
  • Tutorial: Publishing Hello COBOL World to the Cloud
  • Demonstration Programs for COBOL Azure
  • Preparing a COBOL Application for Azure
  • Cloud Template and Skeleton Roles and Projects
  • Accessing Data Using Cloud Drives
  • How to Create and Publish a COBOL Service for Azure
  • Using the Consolidated Tracing Facility on Azure
  • Microsoft Information on Azure and the Cloud


Introduction to COBOL on Azure

Microsoft Windows Azure is a flexible cloud-computing environment for running applications. You develop your application on-premises using the Azure compute emulator (which is Microsoft's local simulation of running your application on Azure) and then deploy and run the application on Azure. The Microsoft Azure platform provides a group of cloud technologies each providing a set of services to application developers, such as the following fundamental components:

  • The Windows Azure AppFabric, which provides a common way to manage and monitor applications that use this cloud platform
  • SQL Azure Database, which is a cloud-based relational database service built on SQL Server technologies
  • Windows Azure Marketplace, which is an online service for purchasing cloud-based data and applications

Micro Focus Visual COBOL provides COBOL-specific functionality within Visual Studio, enabling you to build COBOL applications for Windows Azure. It provides:

  • Project template for a COBOL cloud service. This creates a solution containing a project for the cloud service and projects for the web and worker roles you specify.
  • Demonstration projects, showing a web and worker role in COBOL, with the business logic remaining in unchanged COBOL programs.
  • Virtual hard drive (VHD) upload tool, for uploading data files to Azure.
  • Help. This includes a tutorial that shows how to create a simple cloud service for COBOL and how to deploy and run the service as an off-premises Azure instance.

Before creating your COBOL cloud service, you need to decide on the structure of the solution, its projects and its web and worker roles. For example, you might want to provide a new user interface as part of the web role. You might want to retain some existing COBOL business logic, and use a worker role to communicate with the business logic. You also need to decide how to handle your data, as blobs or table storage, and whether you can use queues. Another preparatory task is to migrate any native-only COBOL that you need, since Azure services are .NET managed code.

To create the COBOL cloud service, you create a project using the COBOL cloud template and then follow a wizard to choose the worker and web roles you require. This creates a solution, with the appropriate skeleton projects and skeleton web and worker roles. You then populate the projects with your code.

You build the COBOL service and test it locally using the compute emulator, then finally you publish to Azure and test there.

Parent topic: Micro Focus Visual COBOL Azure AddPack
Related information
Tutorial: Publishing Hello COBOL World to the Cloud
Preparing a COBOL Application for Azure
Cloud Template and Skeleton Roles and Projects
How to Create and Publish a COBOL Service for Azure


Azure Prerequisites and Levels of Support

Microsoft requires some software. For full details, see the Microsoft Windows Azure web site. At the time of writing, the following are some of the prerequisites:

  • Windows 7, Windows Vista® SP1 or higher, or Windows Server® 2008
  • Windows Azure tools for Visual Studio 1.6 - this includes the Windows Azure SDK
  • Internet Information Services (IIS) 7.0 - This must be installed and enabled, with ASP.NET, which is not enabled by default

Currently, the following are not supported for COBOL applications:

  • Native code
  • Windows Azure Platform Appliance, which is a turnkey cloud platform that you can deploy in your own datacenter

Hints and Tips:

  • You need to run IDE with elevated permissions (administration mode).
  • You use the compute emulator to debug your service locally before publishing to Azure.
Parent topic: Micro Focus Visual COBOL Azure AddPack


Tutorial: Publishing Hello COBOL World to the Cloud

In this tutorial you create a "Hello COBOL World" cloud service which you then deploy and run under Windows Azure. The main steps are:

  1. Create a COBOL cloud solution, comprising a cloud service and a web role.
  2. Add the "Hello COBOL World" code to the web role.
  3. Run the service in the compute emulator and debug it.
  4. Publish and deploy the service to the cloud.

Create a COBOL Cloud Solution

First, create a COBOL cloud solution using the COBOL cloud template in the IDE, and choose a web role only, as follows:

  1. Run Visual Studio as administrator. To do this, go to Start > All Programs > Micro Focus Visual COBOL, right-click Visual COBOL for Visual Studio 2010 and then choose Run as administrator.
  2. Click File > New > Project.
  3. Expand COBOL and click Cloud.
  4. Enter a name for your project, such as "Hello COBOL World" and enter a name and location for your solution. Click OK.
  5. Choose ASP.NET Web Role to create just a web role. Click > and then OK.

The newly-created solution contains two projects: one for the cloud service and one for the web role. The service project contains the service configuration and definition files, and also an association with the web role. You can see all this in Solution Explorer.

Edit the code in the web role

For this simple service just add the "Hello COBOL World" text, as follows:

  1. In the web role project, open the Default.apsx file.
  2. In the Designer view, add some text such as Hello COBOL World. You could also add buttons and other UI controls from the Toolbox.
  3. Save the file.

Run and debug the service

Now you can build the solution and start testing it locally in the compute emulator, as follows:

  1. Build the solution. You can do this from the Build menu.
  2. Start debugging. You can do this from the Debug menu.

    This starts the compute emulator, which is the local development environment. The compute emulator may take some time to start up the first time you run the application.

    Your application then runs and if appropriate the web browser opens and displays your web page.

  3. Show the compute emulator UI. To do this, right-click the Windows Azure Emulator icon in the Windows taskbar or notification area, and choose Show Compute Emulator UI.

    In the compute emulator, monitor your application while it is running and start and stop it as necessary. You can see your trace messages in the compute emulator and verify the application's basic functionality.

Publish and deploy to Azure

Before you deploy your service to the cloud, you must create an Azure account. In addition, before you deploy directly from Visual Studio, you need to create the following items that enable Visual Studio to authenticate your credentials with Windows Azure:

  • A Windows Azure subscription
  • A Windows Azure hosted service
  • A Windows Azure storage account

You create your account and the above items through the Windows Azure Developer Portal

To publish and deploy to Azure:

  1. Publish your solution, by clicking Build > Publish Solution-name .
  2. Click Deploy your Cloud Service to Windows Azure.
  3. Set up your credentials to authorize Visual Studio to manage and deploy your service, as follows:
    1. In Credentials, click the down arrow and click Add....
    2. Fill in the details on the screen, such as the certificate and your subscription ID.

      For Microsoft Help on how to do this, click Help me set up my credentials.

    3. Click OK.
  4. Fill in the rest of the cloud service details, such as the hosted service slot and the storage account.
  5. Click OK.


Demonstration Programs for COBOL Azure

The demonstration programs for COBOL Azure are available by default in %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples\Azure:

The following demonstrations are available:

AzureBookDemo
This demonstration is a Visual Studio solution containing an Azure service consisting of a web role and a worker role that interact with an existing COBOL program. The web role consists of a COBOL program (BookWrapper.cbl) providing the user interface for the service. The worker role demonstrates how you can communicate with the web role by using Azure queue storage and how you can call an existing COBOL program (book.cbl) to perform the business logic.

WorkerRole.cbl - contains the code to start and run the worker role. It reads the role configuration and uses queues for communicating with the web role. It contains the following methods:

  • Run - Run the role. Create the message queues, mount the virtual hard drive and process the messages on the queues.
  • OnStart - Initialization. Start the DiagnosticMonitor and set up delegate to handle Role changes.
  • ConfigurationSettingPublisher - Delegate to set up the RoleChangeHandler. On each invocation this adds a RoleChangeHandler which has been moved into a separate class (RoleChangeHandler) in order to allow arguments to be passed when it is created.
  • CreateMessageQueues - Set up the Azure queue storage. Create the message queues used to pass the book information between the web and worker roles.
  • MountVirtualDrive - Mount a virtual hard drive containing the COBOL data files and use a dd_ mapping to point to the data file on the virtual drive.
  • HandleMessage - Handle an incoming request queue, call the legacy code with the supplied book-details and post the response.
  • OnStop - Called when the role stops. Unmount the drive to ensure it gets released.

Global.asax.cbl - contains the following methods:

  • Application_Start - Set up delegate to handle role changes.
  • ConfigurationSettingPublisher - Delegate to set up the RoleChangeHandler. On each invocation this adds a RoleChangeHandler which has been moved into a separate class (RoleChangeHandler) in order to allow arguments to be passed when it is created.
AzureSQL
This demonstration shows how to use ESQL running on SQL Azure. It shows how you can work locally on SQL Server 2008 R2 and how you can switch to a SQL Azure database with minimal change.
AzureStorage
This demonstration is a Visual Studio solution containing an Azure service consisting of a web role that interacts with an existing COBOL program. The web role consists of C# and COBOL program (CustomerInfoDataContext.cbl) providing the C# ASP. NET with all the information to create, edit, update and delete customer information storage in the Azure Table Storage.
AzureTracing
This demonstration includes a Visual Studio solution for an Azure service which consists of a worker role that calls a COBOL program on startup and writes a number of trace records using the COBOL tracing APIs.
SqlAzureBookDemo
This demonstration is a Visual Studio solution for an Azure service that consists of a web role and a worker role interacting with an existing COBOL program. The web role consists of a C# and COBOL program (SqlBookWrapper.cbl) which provides the user interface for the service. The worker role demonstrates how to use an Azure queue storage to communicate with a web role and call an existing COBOL program (sqlbook.cbl) to perform the business logic.
Thumbnails
This demonstration is a COBOL version of the Microsoft Thumbnails sample that ships with the Microsoft Azure SDK. It is a service that demonstrates a web role and a worker role. The web role provides a user interface for uploading photos and adds a work item to a queue. The worker role fetches the work item and creates thumbnails in the designated directory.
vhdupload
This application is a tool for your use, more than a demonstration. It is a Visual Studio solution containing a console application that demonstrates the use of Microsoft.WindowsAzure.StorageClient to upload a virtual hard drive to Azure as a page blob. This can then be used by an Azure application, such as the AzureBookDemo, to provide traditional file handling. The program is a translation of sample code taken from Andy Edwards of Microsoft.

The demonstrations are documented fully in their readme files, which are also in the above location. The readmes explain how to run the demonstration, together with a description of each file and its references to Microsoft.Windows.Azure.

Parent topic: Micro Focus Visual COBOL Azure AddPack
Related information
Tutorial: Publishing Hello COBOL World to the Cloud
Microsoft Information on Azure and the Cloud


Preparing a COBOL Application for Azure

Before creating your COBOL cloud service, you need to decide on the structure of the solution, its projects, its roles and any existing COBOL code. You also need to decide how to handle your data, as blobs, table storage, SQL Azure, or cloud drives, and whether you can use queues.

Solution, Project and Roles Structure

You can structure your solution with multiple projects and then add references to those projects in the required roles (see the project's References).

Your Azure service can have one or more web and worker roles. These roles can interact with the runtime environment by using the Windows Azure Managed API. The bulk of your existing source code and business logic probably belongs in one or more separate projects in the solution. Some of the code might belong in the web or worker roles projects.

The solution can include the following:

  • Web roles. Use these for the user interface, for interaction with the user and to pass data to and from the user.
  • Worker roles. Use these for general development tasks, such as background processing for a web role. The worker role can interact between the web role and any business logic in other projects that aren't role based.
  • Projects that are not part of any role. Use these for business logic and potentially existing code that does not need to change.

You need to identify any existing COBOL code that is restricted to native COBOL and migrate it so that it can be built as .NET managed code.

Data Storage

You can handle your data using blobs, table storage, queues, or SQL Azure.

You can use existing data, by using a virtual hard drive as a cloud drive.

To handle queues, you might need code to:

  • Create request/response queues
  • Add info to queues and send requests
  • Receive the response from the queue and pass it back to the business logic

To handle table storage, you might need code to:

  • Create the table context
  • Initialize the table
  • Get a queryable object
  • Handle the table data
Parent topic: Micro Focus Visual COBOL Azure AddPack
Related information
Demonstration Programs for COBOL Azure
How to Create and Publish a COBOL Service for Azure
Microsoft Information on Azure and the Cloud


Cloud Template and Skeleton Roles and Projects

A COBOL template is provided for creating a solution for a cloud application or service, with projects for the web and worker roles you choose.

Cloud Service for COBOL

The main project is the cloud service. It defines the roles in the service and contains associations to the roles' projects in the solution.

The properties for each role define its configuration settings, connection settings, end points, local storage resources and more. You edit these settings through the role's properties.

The service definition and service configuration files are xml files representing the roles' properties. The service definition file establishes the run-time parameters for the service and the service configuration file sets the parameters for a running instance of a service.

By default, the Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString for each role is set to use the storage emulator. This specifies the storage account that Windows Azure Diagnostics will use to transfer logging data. Before you deploy your service, you set the cloud configuration to point to a valid storage account in Windows Azure.

To use Azure queue storage, you need to set the DataConnectionString to use the storage emulator.

ASP .NET Web Role for COBOL

The web role is the presentation layer for the application. The skeleton web role comprises:

  • Default.aspx and the code behind in Default.aspx.cbl - Two partial classes that make up a skeleton Web page with controls for the user to interact with your application. You can view the page in the Designer, both as HTML source and as the finished design.
  • About.aspx and the code behind in About.aspx.cbl - Similar to Default.aspx, two partial classes that make up a skeleton About page.
  • Global.asax and the code behind in Global.asax.cbl - The class that handles starting and stopping the application and session.
  • WebRole.cbl - The class containing the methods to start and stop the web role.
  • Web.Debug.config and Web.Release.config - Configuration for the web role.
  • References to Azure classes, such as MicroFocus.COBOL.Runtime.Azure, Microsoft.WindowsAzureServiceRuntime and Microsoft.WindowsAzure.Diagnostics.

WCF Service Web Role for COBOL

This web role is for use with WCF services. The skeleton web role comprises:

  • IService1.cbl - The interface to your WCF service. You add your service operations here.
  • Service1.svc and the code behind Service1.svc.cbl - The class containing the methods to get data and use the data contract.
  • WebRole.cbl - The class containing the methods to stop and start the web role.
  • Web.config - Configuration for the web role.
  • AzureLocalStorageTraceListener.cbl - The class to get the log directory for trace information.
  • References to Azure classes, such as MicroFocus.COBOL.Runtime.Azure, Microsoft.WindowsAzureServiceRuntime and Microsoft.WindowsAzure.Diagnostics.

Worker Role for COBOL

The worker role is similar to a web role but isn't hosted by Internet Information Services (IIS). You usually use the worker role for background processing, such as communicating with the web role and your business logic.

The skeleton worker role includes WorkerRole.cbl - A skeleton COBOL program, which writes a line repeatedly, so that you can see it working. You add you business logic to the skeleton code in this role. It contains the following methods:

  • Run - Run the role.
  • OnStart - Initialization. Start the DiagnosticMonitor and set up delegate to handle role changes.
  • RoleEnvironmentChanging - Handles changes in configuration or environment settings.

Similar to the web roles, the worker also includes references to Azure classes, such as MicroFocus.COBOL.Runtime.Azure, Microsoft.WindowsAzureServiceRuntime and Microsoft.WindowsAzure.Diagnostics.

Parent topic: Micro Focus Visual COBOL Azure AddPack
Related information
Demonstration Programs for COBOL Azure
How to Create and Publish a COBOL Service for Azure
To configure a service and storage for Azure
Microsoft Information on Azure and the Cloud


Accessing Data Using Cloud Drives

You can access your application data by using a cloud drive. You upload your data to Azure storage and access it using the cloud drive APIs.

For example, the demonstration AzureBookDemo accesses the data files in an uploaded virtual hard drive using a cloud drive. The virtual hard drive contains pre-existing COBOL data files (.dat and .idx files). AzureBookDemo's worker role contains code to:

Mount the VHD

AzureBookDemo creates a cloud drive for the AzureBookDemo data (BookData.vhd), using the Azure API and then mounts the cloud drive.

A cloud drive requires a cache. This has to be specified in the Local Storage property of the role. For example: In the AzureBookDemo the cache is named BookDataCache and is set to 32Mb.

method-id MountVirtualDrive private.
  ...
  set driveCache to type RoleEnvironment::GetLocalResource("BookDataCache")
  invoke type  CloudDrive::InitializeCache(driveCache::RootPath, driveCache::MaximumSizeInMegabytes)
  ...
  *> Get the full name of the VHD and create a Cloud Drive for it
  set blobClient to type CloudStorageAccountStorageClientExtensions::CreateCloudBlobClient(storageAccount)
  ...
  set vhdUri to type String::Concat(vhdUri, "vhd/BookData.VHD")
  set theDrive to type CloudStorageAccountCloudDriveExtensions::CreateCloudDrive(storageAccount, vhdUri)
  ...
  *> Mount the drive with a 16Mb cache
  set driveLetterString to myCloudDrive::Mount(16, type DriveMountOptions::None)
Define the location of the data

AzureBookDemo defines the location of the data (bookfile.dat) on the cloud drive. It does this by setting a dd_ environment variable to the name of the file on the virtual drive to allow BookLegacy to access the data. For example:

  set bookPath to type Path::Combine(driveletterString, "bookfile.dat")
  ...
  display "dd_bookfile" upon environment-name
  display bookPath upon environment-value
Parent topic: Micro Focus Visual COBOL Azure AddPack
Related information
To use a cloud drive
Microsoft Information on Azure and the Cloud


How to Create and Publish a COBOL Service for Azure

  • To create a COBOL Azure service and roles
  • To develop a COBOL Azure service
  • To configure a service and storage for Azure
  • To use a cloud drive
  • To debug a COBOL Azure service locally
  • To publish a COBOL service to Azure
  • To run Visual Studio as administrator
Parent topic: Micro Focus Visual COBOL Azure AddPack


To create a COBOL Azure service and roles

  1. Run Visual Studio as administrator.
  2. Click File > New > Project.
  3. Expand COBOL and click Cloud.
  4. Choose the version of the .NET Framework you require.
  5. Enter a name and location for your project and a name for your solution. Click OK.
  6. Choose the roles you require, by clicking one or more of Worker Role, ASP.NET Web Role, WCF Service Web Role.
  7. Click > and then OK.

The new solution is created and packaged as a cloud service. The cloud service project contains information about the roles created and the service configuration and definition files. The solution also contains skeleton projects for the worker and web roles that you specified. You can see all this in Solution Explorer.

Parent topic: How to Create and Publish a COBOL Service for Azure
Related information
Preparing a COBOL Application for Azure
Cloud Template and Skeleton Roles and Projects
To run Visual Studio as administrator
Microsoft Information on Azure and the Cloud


To develop a COBOL Azure service

  1. Run Visual Studio as administrator.
  2. Open the solution for your COBOL application.
  3. In the web role project (if you have one), paint your Web page, using the Web Forms designer in Visual Studio. Add code to communicate with the worker role.
  4. In the worker role project (if you have one), add the code to communicate with the web role and with your business logic. To handle queues, you might need code to:
    1. Create request/response queues
    2. Add info to queues and send requests
    3. Receive the response from the queue and pass it back to the business logic
    To handle table storage, you might need code to:
    1. Create the table context
    2. Initialize the table
    3. Get a queryable object
    4. Handle the table data
Parent topic: How to Create and Publish a COBOL Service for Azure
Related information
Preparing a COBOL Application for Azure
Cloud Template and Skeleton Roles and Projects
To run Visual Studio as administrator
Microsoft Information on Azure and the Cloud


To configure a service and storage for Azure

  1. Run Visual Studio as administrator.
  2. Open the solution for your COBOL application, and open the main project for the service.
  3. In Solution Explorer, expand Roles and double-click the role you want to configure.
  4. In the properties for the role, go to the Settings page.
  5. Specify the connection information you require.

    For example, for local development, the AzureBookDemo sample uses:

    • Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString is set to UseDevelopmentStorage=true
    • DataConnectionString is set to UseDevelopmentStorage=true

    When you have tested locally and you publish to Azure, instead of using local development storage, you need to specify the storage credentials on Azure: your account name and key, connection endpoints and so on. You are given a key when you create your Azure account. See the Microsoft Azure Help for details, which explains the configuration differences between a development system and a live Azure system.

    Note:

    When you set the DataConnectionString you must use http endpoints as required by the cloud drive support.

Parent topic: How to Create and Publish a COBOL Service for Azure
Related information
Cloud Template and Skeleton Roles and Projects


To use a cloud drive

  1. Create a virtual hard drive and copy your data files into it.
  2. Upload the virtual hard drive to Azure. To do this, you can use the vhdupload tool, which is supplied in the Samples folder %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples\Azure.
  3. In your role, add code to:
    1. Create a cloud drive
    2. Mount the virtual hard drive as the cloud drive
    3. Concatenate the drive letter with the filename of the data file.

    See the AzureBookDemo sample for how to do this.

Parent topic: How to Create and Publish a COBOL Service for Azure
Related information
Preparing a COBOL Application for Azure
Accessing Data Using Cloud Drives
Microsoft Information on Azure and the Cloud


To debug a COBOL Azure service locally

  1. Run Visual Studio as administrator.
  2. Open the solution for your COBOL application.
  3. Optionally, add some trace messages to your source code such as the following:
    invoke type Trace::WriteLine("Working", "Information")
  4. Ensure the application can locate your data, by configuring the connection strings for the storage service.

    For example, in the AzureBookDemo sample, DataConnectionString is set to UseDevelopmentStorage=true

  5. Build the solution and start debugging. To do this in one step, click Debug > Start Debugging.
  6. Display the storage emulator UI. To do this, right-click the Windows Azure Emulator icon in the Windows taskbar or notification area, and choose Show Storage Emulator UI.
  7. In the storage emulator, monitor your application while it is running and start and stop it as necessary. You can see your trace messages in the compute emulator and verify the application's basic functionality.
  8. Display the storage emulator UI, in a similar way to displaying the storage emulator UI. In the storage UI, you can monitor your Azure storage, and you can display the cloud drive in Windows explorer.
Parent topic: How to Create and Publish a COBOL Service for Azure
Related information
Cloud Template and Skeleton Roles and Projects
To run Visual Studio as administrator
Microsoft Information on Azure and the Cloud


To publish a COBOL service to Azure

Before you deploy your service to the cloud, you must create an Azure account. In addition, before you deploy directly from Visual Studio, you must create the following items that enable Visual Studio to authenticate your credentials with Windows Azure:

  • A Windows Azure subscription
  • A Windows Azure hosted service
  • A Windows Azure storage account

To publish a COBOL service to Azure:

  1. Create your Azure account and the above items through the Windows Azure Developer Portal.
  2. Run Visual Studio as administrator.
  3. Open the solution.
  4. Specify the diagnostic and storage connection information in the Cloud configuration settings in the solution, as required. See the Microsoft Azure Help for details, which explain the configuration differences between a development system and a live Azure system.
  5. Build your solution, by clicking Build > Build Solution-name .
  6. Publish your solution, by clicking Build > Publish Solution-name .
  7. Click Deploy your Cloud Service to Windows Azure.

    Alternatively, you can click Create Service Package Only, which creates a package locally. You then deploy the package to Azure later, using command line tools, instead of following these instructions.

  8. Set up your credentials to authorize Visual Studio to manage and deploy your service, as follows:
    1. In Credentials, click the down arrow and click Add....
    2. Fill in the details on the screen, such as the certificate and your subscription ID.

      For Microsoft Help on how to do this, click Help me set up my credentials.

    3. Click OK.
  9. Fill in the rest of the cloud service details, such as the hosted service slot and the storage account.
  10. Click OK.
  11. Upload any existing data to the Azure storage service. You can upload blob data using the vhdupload tool, which is supplied in the Samples folder, which is by default %PUBLIC%\Documents\Micro Focus\Visual COBOL\Samples.
Parent topic: How to Create and Publish a COBOL Service for Azure
Related information
To run Visual Studio as administrator
Microsoft Information on Azure and the Cloud


To run Visual Studio as administrator

  1. Go to Start > All Programs > Micro Focus Visual COBOL.
  2. Right-click Visual COBOL for Visual Studio 2010.
  3. Click Run as administrator.
Parent topic: How to Create and Publish a COBOL Service for Azure


Using the Consolidated Tracing Facility on Azure

The Consolidated Tracing Facility (CTF) is a tracing infrastructure that enables you to quickly and easily produce diagnostic information detailing the operation of your applications. This section describes the Azure-specific functionality that is provided by CTF and assumes that you are familiar with the operation of CTF in a non-Azure environment. See your Visual COBOL documentation for information on CTF.

You use CTF on Azure in the same way as you use CTF in non-Azure environments, with the following additional steps:

  1. Update your CTF configuration file to specify one of the two new Azure-specific emitters.
  2. Update the configuration files for your Azure roles.
  3. Add a reference to MicroFocus.COBOL.Tracing.Azure.dll.

Once you have performed these additional steps you run your application as normal for CTF to produce the trace information, then you download the trace information (if the application was run on Azure rather than locally) and view it.

Note:

A sample program, AzureTracing, is available in the Samples Browser and contains a worker role which creates trace entries on startup.

  • Specifying Azure-specific Emitters
  • Updating Azure Role Configuration Files
  • Adding a Reference to MicroFocus.COBOL.Tracing.Azure
  • Downloading Trace Information
  • Viewing Trace Information
Parent topic: Micro Focus Visual COBOL Azure AddPack


Specifying Azure-specific Emitters

To use CTF on Azure you use one of the following emitters:

BINSTORAGE
Writes to Azure table storage in binary format. Before you can view the trace files output by the BINSTORAGE emitter you download them from Azure table storage to a local file using the ctfazure utility. Once you have done this you can view the local file using the CTFViewer utility.
TEXTSTORAGE
Writes to Azure table storage in text format. Before you can view the trace files output by the TEXTSTORAGE emitter you download them from Azure table storage to a local file using the ctfazure utility. Once you have done this you can view the local file using any text editor.
  • BINSTORAGE Emitter Properties
  • TEXTSTORAGE Emitter Properties
Parent topic: Using the Consolidated Tracing Facility on Azure


BINSTORAGE Emitter Properties

Writes to Azure table storage in binary format.

Before you can view the trace files output by the BINSTORAGE emitter you download them from Azure table storage to a local file using the ctfazure utility. Once you have done this you can view the local file using the CTFViewer utility.

To enable the BINSTORAGE emitter, specify the following statement in the Consolidated Tracing Facility configuration file:

mftrace.dest = binstorage

The following list shows the properties you can set to control the behavior of the BINSTORAGE emitter:

StorageAccount
The name of the Azure storage account to be used. The names of the storage accounts you have created can be found in the "Storage Accounts" section of the Azure management portal.

Default: None

StorageKey
The Azure storage access key. When a storage account is selected in the "Storage Accounts" section of the Azure management portal, its associated primary and secondary access keys are displayed in the Properties window.

Default: None

TableName
The name of the table where trace events are to be written.

Default: MicroFocus0CTF0Binary0Storage

Parent topic: Specifying Azure-specific Emitters
Related information
Downloading Trace Information
TEXTSTORAGE Emitter Properties


TEXTSTORAGE Emitter Properties

Writes to Azure table storage in text format.

Before you can view the trace files output by the TEXTSTORAGE emitter you download them from Azure table storage to a local file using the ctfazure utility. Once you have done this you can view the local file using any text editor.

To enable the TEXTSTORAGE emitter, specify the following statement in the Consolidated Tracing Facility configuration file:

mftrace.dest = textstorage

The following list shows the properties you can set to control the behavior of the TEXTSTORAGE emitter:

DelimChar
The character used in the output file to delimit trace data parts for a trace event.

Default: space

Format
The format to be used for each trace data record written to the file. The following pseudo-variables may be used in the format specification:
$(COMPONENT) | the name of the component outputting the trace event.
$(DATA) | the trace data specified by the component to be output for the trace event. Each trace part will be delimited by the character specified by the DelimChar property.
$(DATE) | the current date output as yyyy/mm/dd.
$(EVENT) | the event identifier as specified by the component outputting the trace event.
$(LEVEL) | the tracing level.
$(MACHINE) | the name of the machine running the process .
$(PID) / $(PROCESS) | the current process identifier.
$(TIME) | the current time output as hh:mm:ss.nnn.
$(THREAD) | the current thread identifier. Note that this is the operating system's thread id, not the COBOL run-time system thread id.

Default: $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)

HexBlockSize
The number of hexadecimal bytes to be output in each block. Each block of hexadecimal characters is separated by a hyphen (-) character.

For example, if HexBlockSize is set to 4, and some binary trace data with the value 3132333435363738393A3B3C3D3E3F is specified for output, it is formatted as follows:

31323334-35363738-393A3B3C-3D3E3F

Default: 8

QuoteString
Indicates whether string trace data is to be output enclosed in double-quote characters (").

Default: TRUE

StorageAccount
The name of the Azure storage account to be used. The names of the storage accounts you have created can be found in the "Storage Accounts" section of the Azure management portal.

Default: None

StorageKey
The Azure storage access key. When a storage account is selected in the "Storage Accounts" section of the Azure management portal, its associated primary and secondary access keys are displayed in the Properties window.

Default: None

TableName
The name of the table where trace events are to be written.

Default: MicroFocus0CTF0Text0Storage

Parent topic: Specifying Azure-specific Emitters
Related information
Downloading Trace Information
BINSTORAGE Emitter Properties


Updating Azure Role Configuration Files

To add tracing to your Azure role you must add the following to the configSections element of the configuration file for your role (app.config for worker roles or web.config for web roles).

    <!--The following code declares a section group for tracing configuration -->
    <sectionGroup name="MicroFocus.COBOL.Tracing">
      <section name="mftrace_config"
       type="MicroFocus.COBOL.Runtime.CdataSectionHandler,
         MicroFocus.COBOL.Runtime.Azure,Version=4.0.0.0,Culture=neutral,
         PublicKeyToken=0412c5e0b2aaa8f0" />
    </sectionGroup>
Parent topic: Using the Consolidated Tracing Facility on Azure


Adding a Reference to MicroFocus.COBOL.Tracing.Azure

To enable CTF tracing for an application you must edit the solution in Visual Studio to include a reference to MicroFocus.COBOL.Tracing.Azure.dll, which is located in %ProgramFiles%\Micro Focus\Visual COBOL\bin\PrivateAssemblies\v4.0 folder. Once you have added the reference, set the Copy Local property to True.

Parent topic: Using the Consolidated Tracing Facility on Azure


Downloading Trace Information

If you used CTF on an application that you ran on Azure (rather than locally) you must download the CTF trace information from Azure table storage before you can view it. To do this you use the ctfazure utility which enables you to list, extract, and delete CTF trace events that have been written to Azure table storage

You run the ctfazure utility from the command line and its format is as follows:

ctfazure action parameters

where:

action

specifies the action that the utility is to perform and can be one of:

delete
Deletes an Azure table containing CTF trace events.
extract
Extracts CTF trace events from Azure table storage into a local trace file.
list
Lists Azure tables containing CTF trace events.
parameters

specify additional information:

-account:account name
The name of the Azure storage account.
-key:account-key
The Azure storage account key.
-file:file name
The name of local trace file to download the CTF trace events to.
-table:table-name
The name of the table in Azure table storage containing the CTF trace events.
-tracetype:trace-type
Used with the extract action to specify the type of trace file that is to be created if the table to be downloaded contains both binary and text events. Valid values for trace-type are BINSTORAGE and TEXTSTORAGE.

Examples:

  • Delete the table named "mytable" from the Azure storage account named "myacc":
    ctfazure delete -table:mytable -account:myacc -key:abc123
  • List all tables containing CTF trace events in the the Azure storage account named "myacc":
    ctfazure list -account:myacc -key:abc123
  • Create a trace file named mytrace.log from the contents of the table named "mytable" in the Azure storage account name "myacc":
    ctfazure extract -file:mytrace.log -table:mytable -account:myacc -key:abc123
Parent topic: Using the Consolidated Tracing Facility on Azure
Related information
Viewing Trace Information


Viewing Trace Information

If you ran your application locally you can view the CTF output using Server Explorer by expanding Windows Azure Storage > (Development) > Tables. You can view trace information created using BINSTORAGE and TEXTSTORAGE in this way.

If you ran your application in Azure, once you've downloaded the CTF records using ctfazure you can view them using a text editor (for those created with TEXTSTORAGE) or the CTF Viewer (for those created with BINSTORAGE).

Parent topic: Using the Consolidated Tracing Facility on Azure
Related information
Downloading Trace Information


Microsoft Information on Azure and the Cloud

For help getting started see the Microsoft Help on Azure, which is available from the Visual Studio Start Page, as follows:

  1. Click View > Start Page.
  2. Go to the Get Started tab.
  3. Click Cloud and choose the item you are interested in.

Information is also available at:

  • About Windows Azure
  • Overview of Windows Azure Service Architecture
  • Building Windows Azure Services
  • Windows Azure Storage Services REST API Reference
  • Windows Azure Managed Library Reference
  • Using the Development Fabric
  • Windows Azure Developer Portal
  • Deploying the Windows Azure Application from Visual Studio
  • Differences Between the Development Fabric and Windows Azure
Parent topic: Micro Focus Visual COBOL Azure AddPack